Link with the CLI · Catena Docs

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:

Shell

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.

Shell

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 <command>.

Link a new agent

In this example, we'll link a new agent named "Billing agent":

Shell

catena link --name "Billing agent"

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.
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.
On the approval screen, the approver chooses the organization (live or sandbox), names the agent, and chooses its policy.
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:

Shell

catena link agent_...

The steps are the same. However, the approver must be signed in to the agent's organization with a role 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:

Shell

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:

--profile <name> on the command
CATENA_PROFILE
The directory binding (longest match)
The default set with catena profiles use
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.

Shell

catena profiles list
catena profiles current
catena profiles use billing-agent
catena profiles bind billing-agent ~/work/billing

Unlink

Shell

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 <name>.

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 <name> --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:

Shell

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.