Installation

LinkSnap ships three flavors of tooling. Pick the one that fits how you work:

• CLI — linksnap on your terminal. Best for one-off operations, scripting, and quick exploration. Doesn't require a project.
• SDK — libraries in Node.js, Python, and Go. Best for embedding LinkSnap in an application.
• Raw API — if you can't or don't want to add a dependency, the REST API is fully documented and authenticated with a standard Bearer token.

This page covers installing the CLI and SDKs. If you want raw API access, skip ahead to the API authentication page.

CLI

The CLI is published on npm as @forjio/linksnap-cli. Install it globally:

npm install -g @forjio/linksnap-cli

Verify the install:

linksnap --version

You should see something like 1.x.y. If you get command not found, your global npm bin directory isn't on your PATH — the npm docs cover how to fix that for your shell.

Sign in with the OIDC device flow:

linksnap auth login

That prints a short user code and opens the verification URL in your browser. Approve the request and the CLI saves a session locally. From there:

linksnap links create --url https://example.com/long/path --slug promo
linksnap links list
linksnap stats show promo

Prefer not to install globally? You can run it as npx @forjio/linksnap-cli <command> for one-off uses, or add it as a dev dependency on a project.

Node.js SDK

The Node SDK is @forjio/linksnap-node:

npm install @forjio/linksnap-node

Or with pnpm / yarn:

pnpm add @forjio/linksnap-node
yarn add @forjio/linksnap-node

It's compatible with Node 18 and later. It ships with TypeScript types out of the box — no @types/* package needed.

Minimal usage with a static API key:

import { LinkSnapClient } from '@forjio/linksnap-node';

const linksnap = new LinkSnapClient({
  apiKey: process.env.LINKSNAP_API_KEY,
});

const link = await linksnap.links.create({
  url: 'https://example.com/long/path',
  slug: 'promo',
});

console.log(link.shortUrl);

The full reference is at SDK → Node.js.

Python SDK

The Python SDK is published on PyPI as forjio-linksnap:

pip install forjio-linksnap

It supports Python 3.9+. Dependencies: httpx (only).

Minimal usage:

from forjio_linksnap import LinkSnapClient
import os

ls = LinkSnapClient(api_key=os.environ["LINKSNAP_API_KEY"])

link = ls.links.create({
    "url": "https://example.com/long/path",
    "slug": "promo",
})

print(link["shortUrl"])
ls.close()

The full reference is at SDK → Python.

Go SDK

The Go SDK lives in the same repo as LinkSnap itself:

go get github.com/hachimi-cat/saas-linksnap/sdk/go

Import it as linksnap:

import linksnap "github.com/hachimi-cat/saas-linksnap/sdk/go"

Requires Go 1.22+. Minimal usage:

package main

import (
    "context"
    "fmt"
    "os"

    linksnap "github.com/hachimi-cat/saas-linksnap/sdk/go"
)

func main() {
    c := linksnap.NewClient(linksnap.ClientOptions{
        APIKey: os.Getenv("LINKSNAP_API_KEY"),
    })

    link, err := c.Links.Create(context.Background(), linksnap.LinksCreateInput{
        URL:  "https://example.com/long/path",
        Slug: "promo",
    }, "")
    if err != nil {
        panic(err)
    }
    fmt.Println(link.ShortURL)
}

The full reference is at SDK → Go.

Get an API key

All three SDKs and the CLI accept a static API key. To get one:

1. Sign up at linksnap.com — takes about a minute.
2. Open the dashboard and go to Settings → API keys.
3. Click Create API key. Pick a sensible label.
4. Copy the key immediately — we don't show the secret again.

The convention across SDKs is to read credentials from environment variables:

Variable	Purpose
LINKSNAP_API_KEY	Bearer key — never commit, never log
LINKSNAP_BASE_URL	Optional — only set if you're pointing at staging or self-hosted

Don't bake the key into source. Use your environment's secret manager. For local dev, a gitignored .env file plus dotenv is fine. For production, use AWS Secrets Manager, Vault, or your platform's equivalent.

Device flow (no API key)

The SDKs and CLI can also sign in with the OIDC device flow — same Huudis identity as the portal, no API key to manage. See API → Authentication for the full flow. For the CLI, linksnap auth login handles every step.

Sandbox & staging

If you want to test against a non-production LinkSnap instance, point any SDK or the CLI at staging:

export LINKSNAP_BASE_URL=https://staging-linksnap.forjio.com

API keys minted in production don't work in staging and vice versa. Email hello@linksnap.com if you need staging credentials.

Next: shorten a URL

You're ready. Head back to Quickstart for the end-to-end walkthrough, or jump to Concepts to understand the model first.