Reference — CLI

CLI reference

The package ships a linky command with zero runtime dependencies. Works identically in shells, CI, and agent tool wrappers.

Usage

linky create <url1> <url2> [url3] ... [options]
linky <url1> <url2> [url3] ... [options]
linky update <slug> [options]
linky list [--json] [--limit N] [--offset N]
linky get <slug> [--json]
linky history <slug> [--json]
linky insights <slug> [--range 7d|30d|90d] [--json]
linky delete <slug> --force
linky auth set-key <apiKey>
linky auth clear
linky auth whoami [options]
linky auth keys list [--json]
linky auth keys create <name> [--scopes links:read,links:write] [--rate-limit N]
linky auth keys revoke <id>
linky mcp

The create subcommand is optional — any positional arguments that look like URLs are treated as a create call.

Every authed read command supports --json so agents scripting the CLI directly get structured DTOs instead of the human-readable view. The wire shape matches the HTTP API.

Read commands (Sprint 2.8)

Command	Purpose	Notes
`linky list`	List your Linky bundles, newest-updated first.	Org-context keys see org-owned bundles; user keys see personal ones. `--limit` defaults to 20 (max 100); `--offset` paginates.
`linky get <slug>`	Show a single Linky in full detail.	Returns URLs, metadata, owner, and any attached resolution policy.
`linky history <slug>`	Show the append-only edit history.	Every PATCH appends a version. Newest-first;`--json` dumps the full DTO array.
`linky insights <slug>`	Render totals, per-rule breakdown, and a daily sparkline.	Sparkline is TTY-only;`--json` prints the full DTO. Range defaults to 30d.
`linky delete <slug> --force`	Soft-delete a Linky.	Requires `--force` as a typo-guard; no-op without it. Requires admin role on org-owned bundles.

Key management (Sprint 2.8)

Command	Purpose	Notes
`linky auth keys list`	Show active + revoked API keys for the active subject.	Requires `keys:admin`. Prefix shown; secrets never are.
`linky auth keys create <name>`	Mint a new API key. Secret printed ONCE.	`--scopes links:read,links:write,keys:admin` (comma-separated); `--rate-limit N` (per-hour quota, 0 = unlimited, default 1000, max 100000).
`linky auth keys revoke <id>`	Revoke an active key by numeric id.	Idempotent.

Create options

Flag	Value	Notes
`--base-url`	url	Linky API/web base URL. Defaults to `$LINKY_BASE_URL` or `https://getalinky.com`.
`--stdin`	—	Read additional URLs from stdin, one per line.
`--email`	address	Anonymous create only. Flags the claim token for the named recipient so they can bind ownership after signing in.
`--title`	string	Optional title stored with the Linky.
`--description`	string	Optional description stored with the Linky.
`--policy`	path	JSON file containing a `resolutionPolicy`. Use `-` to read policy JSON from stdin.
`--client`	<tool>/<version>	Client attribution sent as the `Linky-Client` header. Malformed values are silently dropped by the server.
`--json`	—	Machine-readable output. Includes `claimToken` and `warning` on anonymous creates.

Update options

Flag	Value	Notes
`--title`	string	Replace the Linky title.
`--description`	string	Replace the description.
`--description-null`	—	Clear the description.
`--url`	url	Repeat to replace the full ordered URL list.
`--urls-file`	path	Replace the URL list from a newline-delimited file.
`--policy`	path	Replace the full resolution policy from JSON.
`--clear-policy`	—	Clear the resolution policy.
`--api-key`	key	Override the stored or env API key for this one command.
`--json`	—	Machine-readable response payload.

Automation auth

Owner-only CLI commands authenticate with a bearer API key, not a browser session. Create a key in the dashboard, then provide it via:

--api-key
$LINKY_API_KEY
stored config from linky auth set-key

Keys carry a scope locked at mint: links:read, links:write (default), or keys:admin. The CLI currently ships with default write capability — pick a narrower scope in the dashboard when minting, for example if you're storing the key in an agent transcript and want the blast radius capped. See the scope matrix →

Examples

Basic create

linky create https://example.com https://example.org

Anonymous. Prints the short URL and a claim URL in green.

Flagged for a named recipient

linky create https://example.com --email alice@example.com --title "Standup bundle"

--email scopes the claim token; the recipient signs in to take ownership.

Born personalized

linky create https://acme.com/docs --policy ./acme-team.policy.json

Policy applies from the first click. Pair with --email on anonymous calls so the claim URL lands with the owner.

Policy from stdin

cat policy.json | linky create \
  https://acme.com/docs \
  --policy - \
  --email alice@acme.com

--policy - reads JSON from stdin. Useful for piping from jq or generators.

URLs from stdin, machine-readable

echo "https://example.com" | linky create --stdin --json

Combine --stdin and --json for scripted pipelines.

Store an API key locally

linky auth set-key $LINKY_API_KEY

Writes the key to ~/.config/linky/config.json with user-only permissions.

Update an owned Linky

linky update abc123 --title "Release bundle v2" --policy ./policy.json

Uses your stored or env API key and appends a new version to history.

Check the active automation subject

linky auth whoami --json

Verifies the current API key and shows whether it authenticates as a user or org.