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.

Not shipped yet

The API is live and stable. The CLI is not: there is no package to install, and the commands on this page are the specification it is being built against rather than a description of something you can run today. Names and flags may still change before the first release.

Everything here maps onto an endpoint that already exists, so nothing on this page is waiting on API work. Until the binary lands, call the API directly.

Install

There is nothing to install yet. When the first release lands it will be a single static binary, published to Homebrew and npm at the same time, with a shell installer for everything else.

The three commands beside this are struck through on purpose. None of them resolve today, and a copy button on a command that 404s wastes your time.

Authenticate

auth login opens a browser, signs you in, mints a scoped key through POST /v1/tokens and stores it. The key, not the session, is what every later command uses.

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
# -> Opened your browser. Waiting for approval...
# -> Signed in as [email protected]
# -> Key "CLI on <hostname>" stored in the system keychain.

linkwise auth status
# Profile   default
# Account   [email protected]  (Pro)
# Key       lw_pat_8fK2...   expires in 90 days
# 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] [--note] [--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

Three search modes, one flag.

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

Search the library. Fast is keyword, semantic is embedding based, hybrid blends both.

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.

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

Synthesize a link to speech.

Account

Who you are and what is left.

linkwise auth loginPOST /v1/tokens

linkwise auth statusGET /v1/me

Show the active profile, its scopes and its expiry.

linkwise auth logoutDELETE /v1/tokens/{id}

Revoke the stored token and remove it from the keychain.

linkwise usageGET /v1/me/usage

Plan, credits and remaining quota.