CLI configuration reference
Configure Atoi CLI paths, endpoints, credentials, runtime overrides, installer behavior, and machine-readable errors.
On this page
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 | Purpose | Handling |
|---|---|---|
~/.atoi/config.json | Non-secret CLI settings, endpoint overrides, local runtime state, and credential metadata. | Read as JSON. An absent or unreadable file resolves to an empty object. |
macOS Keychain service atoi-cli | Operator, host, provider, and channel credentials on macOS when Keychain is available. | Preferred secret backend. Each credential uses an atoi-cli:<account> Keychain account. |
~/.atoi/secrets.json | Secret fallback when Keychain is unavailable or disabled. | Written with mode 0600. The file is removed when its last secret is deleted. |
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 installing @creative-int/atoi-cli.
| Variable | Default | Effect |
|---|---|---|
NPM_TOKEN | Required for GitHub Packages | Authenticate through a temporary 0600 npm config that the installer removes on exit. |
ATOI_CLI_PACKAGE | @creative-int/atoi-cli | Select the package to install. |
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 | Override the package registry. |
ATOI_WEB_URL | https://atoi.app | Override links back to the web app. |
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
NPM_TOKEN=<token> 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 | First response |
|---|---|---|
ATOI_USAGE_ERROR | The command, positional arguments, or flag combination is invalid. | Run the command with --help, then correct the invocation. |
ATOI_VALIDATION_ERROR | A supplied value or requested transition failed validation. | Read the message, inspect the exact target, and retry with valid input. |
ATOI_CONFIG_ERROR | Required local configuration is absent or inconsistent. | Inspect ATOI_HOME, endpoint overrides, and the relevant config command. |
ATOI_RUNTIME_ERROR | A required runtime, credential backend, or execution dependency failed. | Run atoi doctor --json and repair the reported dependency. |
ATOI_CLI_ERROR | An unclassified error reached the CLI boundary. | Capture the machine envelope and reproduce with the smallest command. |
Do not treat a receipt as proof outside its stated boundary. Use Troubleshooting when the command is valid but the backend, runtime, or client remains unavailable.
Was this useful?