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

# Configuration & auth

> Configure environments, script workspaces, and authentication.

## Precedence

Settings resolve in this order, highest priority first:

1. Explicit command-line flags.
2. Corresponding `ATONOM_*` environment variables.
3. Workspace `.atonom/config.toml`.
4. User configuration, located by `atonom config path`.

`ATONOM_CONFIG` overrides the user configuration file path. Use `config show` to see resolved values and paths rather than guessing a platform-specific directory.

## Settings

```toml theme={null}
# .atonom/config.toml — replace the platform URL
base_url = "https://your-atonom-host.example"
lua_service_url = "https://your-sandbox-host.example"
scripts_dir = ".atonom/scripts"
```

`base_url` selects the platform API. `lua_service_url` independently selects the service used by `eval`. `scripts_dir` is relative to the workspace root unless absolute; its default is `.atonom/scripts`.

Environment equivalents are `ATONOM_BASE_URL`, `ATONOM_LUA_SERVICE_URL`, and `ATONOM_SCRIPTS_DIR`. Tokens use `ATONOM_TOKEN` as described below.

```sh theme={null}
atonom config set base_url https://your-atonom-host.example --local
atonom config set scripts_dir scripts --local
atonom config unset scripts_dir --local
atonom config path --json
atonom config show --json
```

Omit `--local` to modify the user configuration. Unsetting a local value reveals any lower-priority user value; it does not necessarily make the effective setting empty.

## Workspace discovery

The CLI walks upward from the current directory and uses the nearest ancestor containing `.atonom/`. If none exists, it uses the current directory. Create local config at the intended project root before working in nested directories.

The manifest lives inside the resolved scripts directory and records file-to-tool links and sync hashes. It is environment-specific. See [Sync & release](/atonom-script/cli/sync).

## Device authentication

```sh theme={null}
atonom login
atonom status
atonom logout
```

Login stores your refresh token in the OS credential store. Short-lived access tokens remain in memory. Credentials are keyed by normalized platform base URL. Successful device login removes legacy plaintext tokens from the active user and workspace config files.

On macOS, device credentials are stored in Keychain. For other systems, follow the authentication instructions supplied with your binary. Automation can use an environment token without storing device credentials.

`config show` reports token overrides and legacy config tokens; its `token_set` field does **not** establish whether device credentials exist in the keychain. Use `status` to check authentication.

## CI and ephemeral tokens

Inject `ATONOM_TOKEN` through your automation system's secret store, then run:

```sh theme={null}
atonom status --json
atonom list --json
```

`--token` and `ATONOM_TOKEN` override stored credentials. They are never persisted or refreshed by the CLI. An expired override can cause 401 responses even after a successful device login; remove the override to return to device authentication.

Do not put tokens in source files, config, fixtures, shell history, or agent prompts. `logout` removes device credentials for the selected host but does not remove environment variables or legacy plaintext config values. Remove obsolete plaintext values with `config unset token` in each relevant scope.


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