> ## Documentation Index > Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt > Use this file to discover all available pages before exploring further. # mutagent login > Sign in to Mutagent, check your sign-in, and choose the workspace and organization commands act on. 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](/cli/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. ```bash theme={null} mutagent login ``` 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. | Flag | What it does | | - | - | | `--browser` | Use browser sign-in without asking. | | `--non-interactive` | Do not ask; use browser sign-in. With `--json`, also pass `--browser`. | | `--org ` | Sign in to this organization. It is preselected on the approval page. | | `--endpoint ` | Sign in to this API address. The default is `https://api.mutagent.io`. | 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](/quickstart/api-keys). | Environment variable | What it does | | - | - | | `MUTAGENT_API_KEY` | Use this key; no browser. | | `MUTAGENT_ENDPOINT` | Sign in to this API address. It wins over `--endpoint`. | | `MUTAGENT_NON_INTERACTIVE=true` | Same as `--non-interactive`. | | `CI=true` | Same as `--non-interactive`. | `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: ```bash theme={null} # A person is available to approve in a browser mutagent login --browser --json # A Mutagent API key is available MUTAGENT_API_KEY=mg_live_... mutagent login --json ``` 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: ```json theme={null} {"success":true,"authenticated":true,"endpoint":"https://api.mutagent.io","workspace":{"id":"","name":"staging"},"organization":{"id":"org_…","name":"acme"},"_directive":{"instruction":"Verify workspace. Run: mutagent workspaces list --json","next":["mutagent workspaces list --json","mutagent usage --json"]}} ``` `"workspace": null` means no workspace is selected yet. Run [`mutagent workspaces use`](#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. ```bash theme={null} mutagent auth status --json ``` ```json theme={null} { "success": true, "authenticated": true, "endpoint": "https://api.mutagent.io", "keyPrefix": "mg_live_...", "defaultWorkspace": "", "defaultOrganization": "org_…", "onboarding": false } ``` 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`](/cli/commands/project-setup#mutagent-init). To check the workspace as well, use [`mutagent workspaces current`](#mutagent-workspaces-current). ## mutagent auth logout Remove the stored credentials from this machine. ```bash theme={null} mutagent auth logout ``` ## 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`. ```bash theme={null} mutagent workspaces list ``` | Flag | What it does | | - | - | | `-l, --limit ` | Return at most `n` workspaces. The default is 50. | | `-o, --offset ` | Skip the first `n` 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. ```bash theme={null} mutagent workspaces use ``` To use another workspace for one command only, pass `--workspace ` before the command. The workspace is chosen in this order: 1. `--workspace ` 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`: ```bash theme={null} mutagent workspaces use staging mutagent env list # lists staging's Environments mutagent env list --workspace prod # lists prod's, for this command only mutagent env list # staging again ``` A name that is not one of your workspaces is refused: ```bash theme={null} mutagent providers list --workspace prd ``` ```text theme={null} Error: No workspace "prd" among your workspaces in acme. See: mutagent workspaces list ``` 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 ` 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. ```bash theme={null} mutagent workspaces current ``` ```text theme={null} ℹ Key scope: workspace ℹ Organization: acme (org_…) ℹ Workspace: Default Workspace () ℹ Key expires: 2026-10-13T15:51:27.381Z ``` 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. ```bash theme={null} mutagent workspaces get ``` ## 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 `. ```bash theme={null} mutagent config set org ``` ## 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. ```bash theme={null} mutagent config get defaultWorkspace ``` ## mutagent config list Show every setting, with the API key masked. `mutagent config ls` is the same command. ```bash theme={null} mutagent config list ``` ## 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. | Exit code and error code | What to do | | - | - | | 3, `AUTH_REQUIRED` | Sign in: `mutagent login`, `mutagent login --browser --json`, or set `MUTAGENT_API_KEY` and run `mutagent login --json`. | | 3, `WORKSPACE_REQUIRED` | Run `mutagent workspaces list --json`, then `mutagent workspaces use `. | | 2, `AUTH_EXPIRED` or `INVALID_API_KEY` | The key expired (after 30 days), was revoked, or is not a Mutagent key. Sign in again. | | 1, `TENANCY_DENIED` | The workspace name is not one of yours in this organization. Check it with `mutagent workspaces list`. | | 1, `ORG_MISMATCH` | `--org` names another organization than your key's. Sign in for it with `mutagent login --org `. | See [Errors and exit codes](/cli/errors). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.