> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# ancha login

> Sign in to your hosted Ancha workspace from this computer with a browser approval. Later commands run their worlds in the workspace.

`ancha login` connects the CLI to your hosted workspace at app.ancha.io. You approve the computer in your browser, and the CLI saves an API key for it. After that, `ancha run` keeps running your agent on your computer, while the tools and their data run in your workspace. The first line of every run says so.

```bash theme={null}
ancha login [options]
```

| Option | Description |
| - | - |
| `--url <url>` | Hosted Ancha address (default: "[https://app.ancha.io](https://app.ancha.io)") |
| `--no-browser` | Print the approval link instead of opening a browser |

## Example

```bash theme={null}
ancha login
```

```text Output theme={null}
Confirm this computer in your browser: https://app.ancha.io/cli/authorize?...
Code: ABCD-EFGH
```

The browser opens a page titled **Allow this computer?** with your computer's name and the same code. Sign in first if it asks you to. Check that the codes match, then click **Approve**. The CLI finishes:

```text Output theme={null}
Signed in as you@company.com.
Hosted world server: https://app.ancha.io/t/<workspace>
Saved to /path/to/home/.config/ancha/credentials.json. Commands use this server until you run ancha logout or pass --server-url.
```

On a machine without a browser, use `--no-browser` and open the printed link anywhere you are signed in.

## What it saves

Approving creates an API key named after your computer. You can see and revoke it under **Settings** in the console. The CLI saves it with the workspace URL in `~/.config/ancha/credentials.json`, readable only by you. `XDG_CONFIG_HOME` or `ANCHA_CREDENTIALS_FILE` move the file. `ANCHA_API_KEY` in the environment takes precedence over the file.

## After signing in

* [`ancha whoami`](https://docs.ancha.io/cli/whoami) shows the workspace commands use; `ancha whoami --verify` also checks that the server accepts the key.
* `ancha run`, `ancha doctor` and `ancha world up` start with `running on hosted https://app.ancha.io/t/<workspace> (from ancha login; --local to run here)`.
* `--local` on any command uses a server on this computer instead, for one command. `ancha logout` forgets the login.
* A key the server rejects fails the command with `AUTH_INVALID` and exit `2`. Run `ancha login` again.

## Errors

| Message | Exit | What to do |
| - | - | - |
| `the approval link expired` | 2 | Run `ancha login` again and approve within 15 minutes. |
| `sign-in was denied in the browser` | 2 | Someone clicked **Deny**. Run `ancha login` again. |
| `cannot reach https://app.ancha.io` | 3 | Check your network and the `--url`. |

For CI, skip `login` and set `ANCHA_SERVER_URL` and `ANCHA_API_KEY`. See [Login and API keys](https://docs.ancha.io/cloud/login-and-api-keys.md) and [CI](https://docs.ancha.io/cloud/ci.md).


## Related topics

- [Login and API keys](https://docs.ancha.io/cloud/login-and-api-keys.md)
- [ancha whoami](https://docs.ancha.io/cli/whoami.md)
- [ancha run](https://docs.ancha.io/cli/run.md)
- [Results in your workspace](https://docs.ancha.io/cloud/results.md)
- [ancha runs](https://docs.ancha.io/cli/runs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.