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

# Login and API keys

> How the CLI and CI authenticate to your hosted workspace: ancha login on a computer, API keys from Settings for CI, where keys are stored, how to check them and how to revoke them.

The CLI talks to your workspace's hosted world server, `https://app.ancha.io/t/<workspace>`, with an API key. You get a key in one of two ways.

## On your computer: `ancha login`

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

The CLI prints a link and a code and opens your browser. On the **Allow this computer?** page, check that the code matches and click **Approve**. Approving creates an API key named after your computer, and the CLI saves it with your workspace URL. Later commands use that workspace until you run `ancha logout`. Use `ancha login --no-browser` on a machine without a browser. See [`ancha login`](https://docs.ancha.io/cli/login).

`ancha whoami` shows which workspace commands use and where that choice came from. `ancha whoami --verify` also asks the server whether it accepts the key. See [`ancha whoami`](https://docs.ancha.io/cli/whoami).

## For CI and scripts: keys from Settings

1. Open **Settings** in the console.
2. Under **API keys**, enter a name such as `GitHub Actions` and choose **Create key**.
3. Copy the key. It is shown only once; if you lose it, revoke it and create another.

The page also shows your hosted world server URL. Store both as CI secrets and set them as environment variables:

```bash theme={null}
ANCHA_SERVER_URL=https://app.ancha.io/t/<workspace>
ANCHA_API_KEY=<a key from Settings>
```

No `ancha login` is needed when these are set. See [CI](https://docs.ancha.io/cloud/ci.md).

## How the CLI finds the key

1. `ANCHA_API_KEY`, if set, for any hosted server.
2. Otherwise the key `ancha login` saved for that server URL.

`ancha login` saves keys in `~/.config/ancha/credentials.json` (or `$XDG_CONFIG_HOME/ancha/credentials.json`), readable only by you. `ANCHA_CREDENTIALS_FILE` moves it. Never commit this file.

Ancha gives your agent only its tools' fake credentials, never the API key. `ancha run` withholds your shell's variables from the agent, including an exported `ANCHA_API_KEY`, unless you name them in `agent.pass_env` or run with `--inherit-env`. See [`ancha run`](https://docs.ancha.io/cli/run#what-the-agent-gets).

## Revoke a key

**Settings** lists every key with its name, a short prefix, when it was created and when it was last used. Choose **Revoke** next to a key to stop it working. `ancha logout` only forgets the key on your computer; revoke it in **Settings** too if the computer is no longer yours.

A request with a missing, revoked or wrong key fails with `AUTH_INVALID` and exit `2`:

```text Output theme={null}
error[AUTH_INVALID]: https://app.ancha.io/t/<workspace> rejected the API key (401)
hint: run `ancha login`, or set ANCHA_API_KEY to a key from https://app.ancha.io/account
```

A request without any key says `needs an API key` instead.

Run `ancha login` again, or set a current `ANCHA_API_KEY`. A server that cannot be reached at all is a different error, `SERVER_UNREACHABLE`, with exit `3`. See [Errors](https://docs.ancha.io/reference/errors.md).


## Related topics

- [ancha login](https://docs.ancha.io/cli/login.md)
- [CI](https://docs.ancha.io/cloud/ci.md)
- [Hosted workspace](https://docs.ancha.io/cloud/overview.md)
- [Troubleshooting](https://docs.ancha.io/troubleshooting.md)
- [ancha whoami](https://docs.ancha.io/cli/whoami.md)


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