Skip to main content
Sign in once per machine. Every other command uses the saved key and the workspace you choose here. Before you start, install the CLI: see Installation. For a step-by-step setup (install, sign in, choose a workspace, check), follow that page.

​
How accounts work

  • An organization is your company or team on Mutagent. You sign in to one organization at a time.
  • A workspace belongs to an organization and holds your LLM providers, Environments, managed agents and cloud sessions. An organization can have several, for example staging and prod.
  • The key the CLI saves when you sign in works in every workspace you are a member of in that organization, for 30 days. You do not sign in again to switch workspaces.

​
mutagent login

Sign in and save a key on this machine. If you have no account, the browser sign-in creates one.
In a terminal, the CLI asks whether to sign in with the browser or an API key. The browser sign-in opens app.mutagent.io, where you sign in and approve the CLI. The CLI waits up to 5 minutes. The workspace you approve becomes the selected one. When the CLI cannot open a browser, it prints the sign-in URL and keeps waiting. That happens under --json and whenever the output is not a terminal, such as in CI or when a coding agent runs the command. Open the URL in any browser to finish. Under --json, the output is one JSON object per line: first {"event":"auth_url","url":"…","expiresAt":"…"} as soon as the URL exists, then the result. With MUTAGENT_API_KEY set, mutagent login checks that key instead of opening a browser. Use this in CI. See API keys. mutagent auth login is the same command with the same flags.

​
Sign in from a coding agent or CI

A coding agent should always pass --json. Use one of these two commands:
With --browser --json, the first line is {"event":"auth_url","url":"…","expiresAt":"…"}. Show the url to the person verbatim and keep the command running until they approve. Without --browser and without MUTAGENT_API_KEY, mutagent login --json cannot ask how to sign in when there is no terminal, so it fails and names both options. On success, the last line is one JSON object, and the exit code is 0:
"workspace": null means no workspace is selected yet. Run mutagent workspaces use. Every command also reads MUTAGENT_API_KEY without mutagent login. Such a key has no saved workspace: set MUTAGENT_WORKSPACE_ID or pass --workspace, because mutagent workspaces use refuses to save a selection for it.

​
mutagent auth status

Check that you are signed in and the server accepts your key. It shows the server endpoint, the first characters of the key, and the configured workspace and organization.
It exits 0 when the server accepts the key, 3 when you are not signed in, 2 when the key expired or was refused, and 1 when the server cannot be reached. onboarding is true when the current directory has a .mutagentrc.json from mutagent init. To check the workspace as well, use mutagent workspaces current.

​
mutagent auth logout

Remove the stored credentials from this machine.

​
mutagent workspaces list

List the workspaces you are a member of in your key’s organization. * marks the selected one. mutagent workspaces ls is the same command, and mutagent workspace is the same as mutagent workspaces.

​
mutagent workspaces use

Select the workspace every later command works in. LLM providers, Environments, managed agents and cloud sessions all belong to a workspace.
To use another workspace for one command only, pass --workspace <name-or-id> before the command. The workspace is chosen in this order:
  1. --workspace <name-or-id> on the command.
  2. The MUTAGENT_WORKSPACE_ID environment variable.
  3. The workspace selected with mutagent workspaces use.
For example, with two workspaces, staging and prod:
A name that is not one of your workspaces is refused:
If two of your workspaces have the same name, pass the ID. Create or rename workspaces in the web app at app.mutagent.io. With MUTAGENT_API_KEY set to a key you did not save with mutagent login, workspaces use refuses (exit 1): pass --workspace or set MUTAGENT_WORKSPACE_ID instead. mutagent config set workspace <name-or-id> does the same as workspaces use.

​
mutagent workspaces current

Show the key’s scope, its organization, and the workspace commands act on. The CLI asks the server, so the answer is checked, not read from your local settings.
With --json it returns scope, organization, workspace and expiresAt. Exit 0 with a workspace object means every command is ready to run. Exit 3 (WORKSPACE_REQUIRED) means no workspace is selected.

​
mutagent workspaces get

Show one workspace.

​
mutagent config set org

Confirm the organization of the key you signed in with. The organization comes from the key, so nothing is stored. If you name another organization, the command fails and tells you to sign in for it with mutagent login --org <id-or-slug>.

​
mutagent config get

Read one setting. The keys are apiKey, endpoint, format, timeout, defaultWorkspace, workspaceName, defaultOrganization, organizationName, and keyScope. The API key is shown masked. A key with no value set is reported as unknown.

​
mutagent config list

Show every setting, with the API key masked. mutagent config ls is the same command.

​
Exit codes

Every command on this page uses the same exit codes: 0 success, 1 failure (usage errors included), 2 key expired or invalid, 3 not signed in or no workspace. See Errors and exit codes.