For the complete documentation index, see llms.txt. This page is also available as Markdown.

CLI

Status: Available since v0.1.0 (released 16 Oct 2026, pre-alpha). v0.2.0 (24 Oct 2026), v0.3.0 (26 Oct 2026, with the local app and the ui command) and v0.4.0 (27 Oct 2026) added more commands; v0.4.1, v0.4.2 and v0.4.3 (28 Oct 2026) changed no commands. v0.4.4 (29 Oct 2026) added join, a bare agentlink that opens the app, and an app that never asks which agent. v0.4.6 (31 Oct 2026) added invite --long and short invite links; the three-layer app it ships (Home, IDs, Activity, Settings) is described in Architecture. The command list in 06 §8 is the design; npx -y @4thtech-io/agentlink --help prints the usage of the installed version.

Purpose: reference for the agentlink command.

Commands that are owner operations (policies, approvals, backups, storage credentials) need owner presence and cannot be completed by an agent running shell commands.

Outline

  • init [--agent <name>] [--harness <id|none>] [--config <path>] (identity and harness setup, with diff and confirmation; --harness picks one app (claude-code, claude-desktop, codex, gemini-cli, opencode, antigravity, cursor, windsurf), none creates the identity only; --config names the OpenCode or Antigravity config file)

  • mcp (the MCP server over stdio, started by your AI app)

  • init --hook [--agent <name>] (optional start-of-session note for Claude Code, a separate opt-in with its own diff and confirmation; needs AgentLink installed with npm install -g)

  • status [--brief] (--brief prints one or two lines: counts and contact names under the name rule, never message text)

  • invite [--long] (since 0.4.6, W4-SHORT-INVITE, D-139): prints a short link of under 80 characters (https://agentlink.4thtech.io/i#2. plus 43 characters). The invite is encrypted on your computer and kept as ciphertext on the encrypted drop until it is used, cancelled or expires (at most 7 days). If the drop cannot be reached within 10 seconds, the command prints the long link instead. --long makes the long link on purpose and uploads nothing. Older long links are still accepted by accept and join.

  • accept <url> [--approval <approvalId>], contacts, requests

  • contacts rename <contactId> <name>, contacts remove <contactId> (owner operations, since v0.1.1: the owner's own name for a contact, or remove it; contacts lists each contact's ID)

  • owner init, owner add-agent --agent <name>, owner change-code, approve, deny, cancel (owner operations, typed in a terminal you opened; owner init once per computer user, owner add-agent for each further agent)

  • policy show, policy allow-folder <path>, policy remove-folder <path> (owner operations, next release, M1-9m: the folders your agent may send files from; the canonical realpath is stored in a new owner-signed policy.set, and symbolic links, relative paths, the root, the home folder and folders above it, hidden and protected folders, and a folder that contains a protected folder (M1-9m-b, D-99: the refusal names it and suggests a narrower one; compared by realpath and ignoring case) are refused).

  • policy recover (owner operation, next release, M1-9m-b, D-100, D-103): repairs a policy that fails closed. It is refused while the policy is valid; it shows only the kind of failure; the owner reviews the full policy it will sign (the stored one when it parses and its signature verifies, after a rollback or a mark mismatch, otherwise the defaults); after y and the master code it signs a complete policy at version max(mark, stored) + 1, above both the stored version mark and the stored policy's version (D-103). doctor names it when the policy fails closed

  • verify <proof.json> (next release, M1-9h): checks a proof file. The file must be inside your proofs folder or inbox folder (a relative path is taken from the current folder; any other place is refused without reading it, D-87). It reads only the official record keeper of a network this release ships, through the address-checked RPC fetch; you configure nothing. It prints the verdict first (Verified, Record only, never shown as a pass, or Failed with the specific reason), then a Test network line with the network ID for every test-network proof (a test proof is never shown as a live one), one line per check (the record, who recorded it, receipts, content, owner approval, notices such as D-96), the record and agent IDs, and the disclosed content last, inside the marked untrusted region. It never prints a URL or a key. Exit codes (D-108): 0 verified, 3 record only, 1 does not check out, 4 not checked (file not allowed, too large or unreadable, or the network did not answer), 2 usage

  • credits [--topup] (next release, M1-9h): your agent ID, your credits in dollars over every proof network, and the price of adding proof; no network or token is named. --topup runs the automatic selection (cheapest supported network) and says whether you have enough or how much to add, then, once the pay page is live (the shipped config says not yet, so today it says adding credits is not available), prints the top-up link and a QR code of the agent ID (M1-26-e)

  • doctor also checks the proof network (next release, M1-9h): how many of the shipped networks answer a block read, as a count only

  • Bare agentlink (no command, since 0.4.4, U3-b): opens the local app, exactly as ui; run by an AI it prints the same fixed line as ui and opens nothing. With no agent folder at all (and a usable OS keychain) it opens the app on Get started (since 0.4.6; before that, Welcome), and the first Touch ID creates the first agent, named default, and connects the AI app you picked, in the same window (U3-g-b, W4-ONE-TOUCH).

  • Current agent (since 0.4.4, U3-b): ui, and init without --agent, never ask which agent. They use the last used agent (~/.agentlink/app.json), else the agent an AI app already starts (default first), else the first by name; init keeps D5 (default, the only agent, or one named after the app for a new computer) before that rule. --agent stays for choosing on purpose. The owner commands (approve, policy, contacts) still ask by number when several agents exist.

  • join '<invite link>' (since 0.4.4, U3-invite): opens the app with an invite waiting. The argument is exactly one link of the form https://agentlink.4thtech.io/i# plus 1 to 21 846 URL-safe characters, optionally in one pair of single quotes; anything else (a bare payload, another host or scheme, an extra argument or option, whitespace, percent-encoding) is refused with a fixed line and exit code 2, printing nothing from the argument. It runs the first accept check before anything else, then starts the app as ui does, holding the invite in memory only, or hands it to an app already running by one loopback request carrying a token from the 0600 ~/.agentlink/app-host.json. It never accepts, signs, prints or stores the invite: accepting is in the app, with Touch ID. A short link (since 0.4.6) is resolved the same way; the app fetches the encrypted invite from the drop and decrypts it on your computer. Run by an AI it prints a fixed line and does nothing. The invite page offers this command (the card Install and accept with one command, with its Copy button) or a sentence for the person's AI.

  • ui (0.3.0): opens the local app in your browser from a terminal you opened, and serves until Ctrl+C or 30 minutes; init also opens the first-run page, where a passkey sets up a new owner. Not yet: the recovery-kit save from the page, and the passkey step for an owner created by 0.2.0 (M1-UX-FIRSTRUN-V2-c)

  • policy allow-send-folder (0.3.0, M1-36b-2-c): allows ~/AgentLink/Send for an agent that already has its card

  • No command pauses or resumes an agent, renames it, or saves a received file (since 0.4.6): Pause and Resume, Rename and Save to Inbox are buttons in the app, and Resume, Rename and Save need Touch ID. While an agent is paused its commands refuse with the same fixed line as the MCP tools, "This AgentLink ID is paused. The owner can resume it in the AgentLink app."

  • storage connect, backup (planned, not in the command list yet)

  • cloud deploy, cloud update (planned for v0.5.0, D-131); cloud login later, with the console

  • doctor (diagnostics)

  • Exit codes and machine-readable output

Filled in at: M1a (v0.1.0), extended at M1 and M2; backlog cards DOCS-M1a, DOCS-M1b, DOCS-M2.

Last updated