Command line

Linkwise CLI

Save, search and read your library without leaving the terminal. Every command is a thin wrapper over one endpoint in the API reference, so anything the CLI can do, a script can do too.

Install

A single static binary with no runtime to install alongside it. Every release publishes to Homebrew and npm at the same time, from the same tag.

The shell installer and the npm package both verify the release checksum before they unpack anything. If it does not match, nothing is written.

Authenticate

auth login opens the dashboard, takes the key you paste, and checks it against GET /v1/me before storing it, so a mistyped key fails at the prompt rather than on your next command. It is kept in the system keychain; on a machine without one the CLI writes it to a 0600 file and tells you it did.

In CI, skip the browser entirely and set LINKWISE_TOKEN. The CLI prefers the environment variable over anything stored, so a pipeline never picks up a developer's credentials by accident.

Terminal

linkwise auth login
# -> Create a key at https://linkwise.app/build/dashboard
# -> Paste key: ****************
# -> Signed in as [email protected]
# -> Key stored in the system keychain.

linkwise auth status
# Profile  default
# Account  [email protected]  (pro)
# Key      lw_pat_8fK...  (from the keychain)
# Scopes   links:read links:write collections:read search:read

Configuration

Resolved in this order, first one wins: a command flag, then the environment, then the config file, then the default.

Environment

LINKWISE_TOKENPersonal access token. Overrides the keychain.

LINKWISE_APIBase URL. Useful for pointing at a staging deploy.

LINKWISE_PROFILEWhich profile to use, for multiple accounts.

NO_COLORAny value disables colour, per the no-color.org convention.

config.toml

default_profile = "default"

[profiles.default]
api = "https://jcbgrqawrvztwsvxawda.supabase.co/functions/v1/api"
# The key lives in the OS keychain, not here. On a machine with
# no keychain the CLI falls back to this file with 0600
# permissions and says so on login rather than doing it silently.

[output]
format = "table"   # table | json
color  = "auto"    # auto | always | never

Output and piping

Human-readable tables on a terminal, machine-readable JSON when piped. The CLI detects this rather than making you remember a flag, and --json forces it either way.

Terminal

# A table, because stdout is a terminal
linkwise ls --limit 3

# NDJSON, because it is not
linkwise ls --limit 3 | jq -r '.url'

# Force it either way
linkwise ls --collection reading --json > backlog.json

Exit codes

Distinct per failure class, so a script can tell "your key expired" from "that link does not exist" without parsing stderr. They map onto the API's error codes.

Codes

0SuccessThe command did what it said.

1ErrorAnything unclassified, including a network failure.

2UsageBad flags or a missing argument. Nothing was sent.

3AuthNo token, or it is invalid, expired or revoked. Maps to unauthorized.

4ForbiddenThe token lacks the scope, or API access is disabled. Maps to forbidden.

5Not foundNo such link, collection or tag. Maps to not_found.

6Rate limitedOver the limit. The CLI already waited and retried once. Maps to rate_limited.

7Plan limitA quota is exhausted or the endpoint is Pro only.

Commands

Each one names the endpoint it calls, so you can drop to curl for anything the CLI does not cover.

Saving

The command you will actually type all day.

linkwise save <url> [--title] [--description] [--collection] [--tag]POST /v1/links

Save a link. Re-running with the same URL returns the existing link rather than creating a duplicate.

linkwise open <id>GET /v1/links/{id}

Open a saved link in the browser.

linkwise read <id> [--raw]GET /v1/links/{id}/content

Print the extracted reader content to stdout, as Markdown by default.

Library

Listing and organising what you have saved.

linkwise ls [--collection] [--tag] [--archived] [--limit]GET /v1/links

List links, newest first. Paginates automatically when piped.

linkwise rm <id>DELETE /v1/links/{id}

Delete a link. Soft delete, recoverable in the app.

linkwise tag <id> <tag>...PUT /v1/links/{id}/tags

Replace the tags on a link. Tags that do not exist are created.

linkwise collections [ls|new|rm]/v1/collections

Manage collections.

linkwise tags [ls|new|rm]/v1/tags

Manage tags.

linkwise highlights [ls|add]/v1/highlights

Read and create highlights.

Finding

Two search modes, one flag.

linkwise search <query> [--mode fast|hybrid]GET /v1/search

Search the library. Fast is keyword only and returns everything at once. Hybrid blends keyword with embeddings, and is the default.

linkwise search --highlights <query>GET /v1/search/highlights

Search inside your highlights instead of your links.

linkwise discover [--save <id>]/v1/discover

Print the recommendation feed, and optionally save one item into the library.

Feeds

RSS in, OPML out.

linkwise feeds [ls|add <url>|rm <id>]/v1/feeds

Manage RSS subscriptions.

linkwise feeds export > linkwise.opmlGET /v1/feeds/export

Export every subscription as OPML, importable by any reader.

AI

Pro only, and streams by default.

linkwise ask <question> [--link <id>] [--collection <id>]POST /v1/chat

Ask a question over one link, one collection or the whole library. Streams to the terminal.

Not available to an API key yet. Needs a signed-in session. The chat and speech functions resolve the caller from a user JWT, so an API key cannot reach them yet.

linkwise say <id> [--voice] [--out file.mp3]POST /v1/tts

Synthesize a link to speech.

Not available to an API key yet. Needs a signed-in session. The chat and speech functions resolve the caller from a user JWT, so an API key cannot reach them yet.

Account

Who you are and what is left.

linkwise auth loginGET /v1/me

Opens the dashboard, takes the key you paste, checks it works and stores it in the system keychain.

linkwise auth statusGET /v1/me

Show the active profile, its scopes, and which source the key came from.

linkwise auth logout-

Remove the stored key from this machine. The key keeps working until you revoke it in the dashboard.

linkwise usageGET /v1/me/usage

Plan, credits and remaining quota.

linkwise completion [bash|zsh|fish]-

Print a shell completion script. Source it from your shell profile.