Skip to main content
The Mutagent CLI (@mutagent/cli) is published on npm. Every other page assumes you have done the four steps on this page: install, sign in, choose a workspace, check.

​
Requirements

You also need a Mutagent account. If you have none, the browser sign-in below creates one.

​
1. Install

Check that the binary is on your PATH:
It prints the version number and exits 0. If the shell says command not found, your package manager’s global bin directory is not on PATH.

​
2. Sign in

Pick the way that fits who is at the keyboard. All three save a key on this machine. The key works in every workspace you belong to in that organization, for 30 days.
The CLI asks whether to sign in with the browser or paste an API key. The browser sign-in opens app.mutagent.io, where you sign in or create an account and approve the CLI. The CLI waits up to 5 minutes. The first sign-in in a terminal ends with a short setup menu.
Every command reads MUTAGENT_API_KEY when it is set, even without mutagent login. A key you never saved with mutagent login has no saved workspace, so mutagent workspaces use refuses it: name the workspace with MUTAGENT_WORKSPACE_ID or --workspace instead. Run mutagent login --json once if you want workspaces use to work.
mutagent login --json without --browser and without MUTAGENT_API_KEY cannot ask how to sign in when there is no terminal, so it fails and tells you to add one of them. To sign in to another organization, name it. It is preselected on the approval page:
All sign-in flags and environment variables are on Sign in.

​
3. Choose a workspace

Every command works in one workspace. Sign-in selects one when it can: the workspace you approved in the browser, or your only workspace. List your workspaces and select one:
In the list, selected: true marks the current workspace. The workspace is chosen in this order: the --workspace flag on the command, then the MUTAGENT_WORKSPACE_ID environment variable, then the workspace you chose with mutagent workspaces use. Create workspaces in the web app at app.mutagent.io.

​
4. Check that it worked

Exit code 0 and a workspace object mean you are ready. The CLI asks the server, so the answer is checked, not read from local settings. mutagent auth status --json checks the sign-in alone. It returns "authenticated": true, the endpoint and keyPrefix, and exits 0 when the server accepts the key. The JSON a successful mutagent login --json prints has the same information:
It also carries _directive.next, the follow-up commands to run after a success; on a failure, read _agentGuidance.fix instead (see which field to read). "workspace": null means no workspace is selected yet: run step 3.

​
Exit codes

No saved key and MUTAGENT_API_KEY is not set. Sign in (step 2).
Run mutagent workspaces list --json, then mutagent workspaces use <workspace-name>. With a MUTAGENT_API_KEY you did not save with mutagent login, set MUTAGENT_WORKSPACE_ID or pass --workspace <name-or-id> instead.
The saved key is older than 30 days, was revoked, or is not a Mutagent key. Sign in again.
Nobody approved the URL within 5 minutes. Run the same command again and approve the new URL.
See Errors and exit codes for every error code.

​
Settings

To inspect the saved settings:

​
Uninstall

To also remove saved credentials, run mutagent auth logout first, or delete ~/.config/mutagent.