CLI configuration reference
Configure Atoi CLI paths, endpoints, credentials, runtime overrides, installer behavior, and machine-readable errors.
Use these settings only when the defaults in the CLI reference do not fit your environment. Prefer CLI flags for one command and environment variables for one process. Keep credentials out of shell history, logs, and checked-in files.
#Configuration files
The CLI uses ~/.atoi by default. Set ATOI_HOME to move the entire directory.
| Path | Holds |
|---|---|
~/.atoi/config.json | Non-secret CLI settings, endpoint overrides, local runtime state, credential metadata |
macOS Keychain service atoi-cli | Operator, host, provider, and channel credentials when Keychain is available |
~/.atoi/secrets.json | The same secrets when Keychain is unavailable or disabled |
The config file is read as JSON, and a missing or unreadable file counts as empty. Keychain is the preferred secret store, one atoi-cli:<account> entry per credential. The secrets file is written with mode 0600 and removed when its last secret goes.
Inspect the active home without printing secrets:
ATOI_HOME=/absolute/path/to/atoi-home atoi status --json
#Runtime environment
| Variable | Default | Effect |
|---|---|---|
ATOI_HOME | ~/.atoi | Move config.json, the fallback secret file, and other CLI-owned state. |
ATOI_CONVEX_SITE_URL | Production Atoi HTTP endpoint | Override the convex.site URL used for HTTP routes. |
CONVEX_SITE_URL | Not set | Supply the HTTP endpoint when ATOI_CONVEX_SITE_URL is absent. |
ATOI_CONVEX_URL | Production Atoi Convex endpoint | Override the convex.cloud URL. |
CONVEX_URL | Derived or production endpoint | Supply the Convex endpoint when ATOI_CONVEX_URL is absent. |
ATOI_WEB_URL | https://atoi.app | Override the web app used for browser-owned flows. |
ATOI_DISABLE_KEYCHAIN | Not set | Set to 1 to use the mode-restricted secret file on macOS. |
ATOI_RUNTIME_BIN | Auto-detected | Run this Atoi runtime binary for durable code work. |
ATOI_REPO_PATH | Auto-detected | Pin the Atoi checkout used for development fallbacks and settings discovery. |
ATOI_TUI_BIN | Auto-detected | Run this TUI binary for atoi tui. |
ATOI_DEBUG | Not set | Set to 1 or true to include optional connect diagnostics. |
ATOI_TOKEN | Stored operator credential | Supply a one-process operator token. Prefer atoi account login for durable use. |
ATOI_HOST_TOKEN | Stored host credential | Supply a one-process host token for host-backed commands. Prefer atoi login for durable use. |
Use Atoi-specific endpoint names in scripts. The unprefixed Convex names are compatibility fallbacks and have lower precedence.
#Installer environment
The installer reads these values only while it runs. Export them before piping the script.
| Variable | Default | Effect |
|---|---|---|
ATOI_INSTALL_CHANNEL | tarball | tarball needs no token; npm installs from the public registry and falls back to the tarball; registry installs from GitHub Packages and needs NPM_TOKEN. |
NPM_TOKEN | Not set | Required only by the registry channel; written to a temporary 0600 npm config that the installer removes on exit. |
ATOI_CLI_TARBALL | https://atoi.app/cli/atoi-cli.tgz | Tarball path or URL for the tarball channel. |
ATOI_NPM_REGISTRY | https://registry.npmjs.org | Registry for the npm channel. |
ATOI_CLI_PACKAGE | @creative-int/atoi-cli | Package for the npm and registry channels. |
ATOI_MIN_NODE_MAJOR | 20 | Set the minimum accepted Node.js major version. |
ATOI_INSTALL_PM | Auto-detected | Prefer npm, pnpm, or bun. |
ATOI_INSTALL_DRY_RUN | 0 | Set to 1 to print planned installer steps without executing them. |
ATOI_INSTALL_FORCE_PM | 0 | Set to 1 to require the selected package manager. |
ATOI_INSTALL_SKIP_IF_PRESENT | 0 | Set to 1 to preserve an already complete atoi command. |
ATOI_PACKAGE_REGISTRY | https://npm.pkg.github.com | Registry for the registry channel. |
ATOI_INSTALL_NO_ANIMATION | Not set | Set to 1 to print the banner without its animation. |
ATOI_INSTALL_ANIMATION_DEMO | Not set | Seconds to show the banner and its install animation, then exit without installing. |
ATOI_WEB_URL | https://atoi.app | Override links back to the web app. |
ATOI_MIN_NODE_MAJOR controls only the installer's preflight. The current CLI package still requires Node.js 22 or newer.
Read the installer before you run it in a restricted environment:
curl -fsSL https://atoi.app/install.sh -o /tmp/atoi-install.sh
less /tmp/atoi-install.sh
bash /tmp/atoi-install.sh
#Machine output
Pass --json or --format json for one canonical JSON envelope. Pass --ndjson when a command emits multiple records. Pass --json-errors when a command supports human output but your caller needs structured failures.
atoi doctor --json
atoi project list --ndjson
#Error classes
The source defines five stable error codes. They currently share the CLI core general nonzero exit class, so branch on the error code rather than assigning different meanings to exit numbers.
| Code | Meaning |
|---|---|
ATOI_USAGE_ERROR | The command, positional arguments, or flag combination is invalid |
ATOI_VALIDATION_ERROR | A supplied value or requested transition failed validation |
ATOI_CONFIG_ERROR | Required local configuration is absent or inconsistent |
ATOI_RUNTIME_ERROR | A required runtime, credential backend, or execution dependency failed |
ATOI_CLI_ERROR | An unclassified error reached the CLI boundary |
A usage error wants --help and a corrected invocation. A validation error names the exact target; fix the input and retry. A config error points at ATOI_HOME, endpoint overrides, or the relevant config command. A runtime error is what atoi doctor --json repairs. For anything unclassified, keep the machine envelope and reproduce it with the smallest command.
Do not treat a receipt as proof outside its stated boundary.
Read Troubleshooting when the command is valid but the backend, runtime, or client stays unavailable.
Was this useful?