# Link with the CLI `catena link` connects a machine (your own computer or a headless VM) to an agent identity in your organization. Once a person approves the link in the console, the CLI will sign each request with a key it keeps on the machine. The link has no session, so there's nothing to expire or refresh. ## Install the CLI The CLI requires Node.js 20 or later on macOS or Linux. To install it globally and confirm the version: ```sh npm i -g @catena/cli catena --version ``` If the global install fails with a permission error, we recommend installing to a user prefix instead. Do not use `sudo`. ```sh npm config set prefix ~/.npm-global export PATH="$HOME/.npm-global/bin:$PATH" npm i -g @catena/cli ``` You can also run any command through npx: `npx -y @catena/cli@latest `. ## Link a new agent In this example, we'll link a new agent named "Billing agent": ```sh catena link --name "Billing agent" ``` 1. The command prints `Not linked yet: waiting for the person to approve.`, an approval link, and a short code, and then exits. The link expires after 15 minutes. 2. The approver opens the link. If they do not have a Catena account, they can sign up from the same link and finish setup first. 3. On the approval screen, the approver chooses the organization (live or [sandbox](https://docs.catena.com/sandbox.md)), names the agent, and chooses its [policy](https://docs.catena.com/policies.md). 4. Run the same command again from the same directory within 24 hours of approval. It prints `Done`. The machine does not need a browser, so this works on a headless VM. ## Link an existing agent To link an agent that already exists, pass its ID: ```sh catena link agent_... ``` The steps are the same. However, the approver must be signed in to the agent's organization with a [role](https://docs.catena.com/team.md) that can approve agent links. If the approver can use this machine's browser, you can add `--browser`. The CLI will open the approval page in that browser and wait for it. ## Link output Below are the outputs that `catena link` may print, and what to do after each one. | Output | Meaning | What to do | | ------------------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------- | | `Not linked yet` and a link | The link is waiting for approval. | Send the link to the approver, and run the command again after they approve. | | `Still waiting for approval.` | The CLI checked once, and it's still waiting. | Wait. Send the link again only if the approver lost it. | | A new link, saying the old one expired | The 15 minutes passed. | Send the new link. The old one no longer works. | | Declined, with an `unlink --force` command | The person denied the request. | Stop, and ask before starting again. | | `Done` | The machine is linked. | Run `catena whoami` to confirm. | | `Already linked as ...` | This profile is already linked. | None. | ## Scheduled agents An agent that runs on a heartbeat should pass the same profile name on every run, starting with the first: ```sh catena link --name "Nightly agent" --profile nightly catena whoami --profile nightly ``` If a run uses a different profile name, it will start a second request. ## Profiles A machine can hold several linked agents, each in its own profile (e.g., `billing-agent`). Profiles are machine-wide and live in `~/.config/catena`, or in `$CATENA_HOME` when it is set. When you run `link`, it binds the current directory to the profile it creates, and later commands in that directory act as the same agent. Note that `link` does not bind your home directory. When a command needs a credential, the CLI selects a profile in the following order: 1. `--profile ` on the command 2. `CATENA_PROFILE` 3. The directory binding (longest match) 4. The default set with `catena profiles use` 5. The only linked profile, when exactly one exists If several profiles exist and none of these selects one, the command will fail and list the profiles. We recommend that an agent host set `CATENA_PROFILE` (which `link` prints when it finishes) instead of depending on the directory binding. ```sh catena profiles list catena profiles current catena profiles use billing-agent catena profiles bind billing-agent ~/work/billing ``` ## Unlink ```sh catena unlink ``` `unlink` ends this machine's link on the server and deletes the profile and its key from the machine. The agent itself remains in the console. To unlink a different profile, add `--profile `. > [!NOTE] **Unlinking with --force** > > `--force` clears a profile without contacting the server, for example after > its key was revoked or a link stopped part way. However, with `--force` the > link will stay active on the server until someone unlinks it in the console. ## Link again You'll need to run `link` again after someone unlinks this machine in the console, or when a command says Catena rejected this machine's signing key. To add a wallet signing key after your organization finishes signing setup, run `catena link agent_... --profile --relink`. The profile will keep working until the new link is approved. ## Install the skill After linking, install the Catena skill, which tells future agent sessions to use the CLI: ```sh npx -y skills add catena-labs/skills --skill catena-cli --global --yes ``` Please do not add these instructions to `CLAUDE.md`, `AGENTS.md`, or other files in your repository. The skill is the method we support. ## Related - [Credential storage](https://docs.catena.com/connect/credentials.md): Where the CLI keeps an agent's signing key on each kind of host, and which credential mode to use when there's no keychain. - [CLI reference](https://docs.catena.com/cli.md): The public commands in @catena/cli 0.19.0, generated from the CLI's help text. - [Troubleshooting](https://docs.catena.com/troubleshooting.md): The errors you may run into while linking, signing, and sending payments, with the cause of each and what to do about it.