> ## 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. # CLI commands > Commands, flags, output fields, and exit codes for the Atonom CLI. Run `atonom --help` for the executable you have installed. Examples use placeholder tool ID `42` and Atonom agent ID `7`. ## Global options Global flags can appear before or after the subcommand: * `--json`: machine-readable output where implemented. `guide` remains text; errors and prompts can still use stderr. * `--base-url URL`: platform API base URL; environment variable `ATONOM_BASE_URL`. * `--token TOKEN`: ephemeral token override; prefer `ATONOM_TOKEN` to keep tokens out of process arguments. * `--lua-service-url URL`: sandbox base URL; environment variable `ATONOM_LUA_SERVICE_URL`. * `--scripts-dir DIR`: local scripts and manifest directory; environment variable `ATONOM_SCRIPTS_DIR`. * `--timeout-secs SECS`: HTTP timeout, default `120`. Values below one are clamped to one. This is not a Lua CPU limit. * `--help` and `--version`: CLI information. ## login / logout ```sh theme={null} atonom login atonom login --no-browser atonom logout ``` Login uses device approval and stores the refresh token in the OS credential store. `--no-browser` prints the URL without opening it. Logout revokes and removes device credentials for the configured host. It does not unset an environment token override. Positional `login TOKEN` and `config set token` are deprecated and rejected. See [Configuration & auth](/atonom-script/cli/configuration). ## config / status / guide ```sh theme={null} atonom config show --json atonom config path --json atonom config set base_url https://your-atonom-host.example --local atonom config unset lua_service_url --local atonom status --json atonom guide ``` Config supports `show`, `path`, `set KEY VALUE [--local]`, and `unset KEY [--local]`. Writable settings are `base_url`, `lua_service_url`, and `scripts_dir`. `status` checks the platform scripts API, not the sandbox. `guide` prints the authoring contract. ## list ```sh theme={null} atonom list --json ``` Returns `scripts` with tool IDs, internal script IDs, names, status, input keys/types, and `local_path` when linked. Use **tool IDs** in CLI commands, never internal script IDs. ## create ```sh theme={null} atonom create "Order total" --comm-agent-id 7 --json ``` Creates a disabled tool and a linked local starter file. The owner is selected automatically if only one Atonom agent is available; otherwise the CLI prompts in human mode and requires a choice in JSON mode. Returns the tool ID, script ID, status, owner, path, hash, and link state. ## pull ```sh theme={null} atonom pull 42 --json atonom pull 42 43 --json atonom pull --json ``` Downloads selected tools, or all visible tools when IDs are omitted. `--force` overwrites locally modified files. Without it, dirty files are skipped. Check `results[].action` even when the command exits successfully. ## get ```sh theme={null} atonom get 42 atonom get 42 --json atonom get 42 --out .atonom/scripts/order-total.lua --json ``` Plain output is the script body; JSON output includes detail such as `input_schema` and `sha256`. `--out PATH` (or `-o PATH`) writes the body and attempts to link it. An output path outside the scripts directory is not linked. Existing destination files are overwritten; use `pull` when you need local-edit protection. ## Targets and linking `push`, `diff`, and `run` accept `TARGET`: an existing file relative to the current directory, a file relative to the scripts directory, a manifest path, or a tool ID. Numeric targets use the manifest's local file when a local body is required. Use `--tool-id ID` to identify an unlinked file's remote target. Keep it inside the configured scripts directory if you want the link remembered. This flag does not create a new remote tool. ## diff ```sh theme={null} atonom diff 42 --json atonom diff order-total.lua ``` Compares local content to the current remote body. JSON includes `identical`, `remote_changed_since_pull`, local/remote/synced hashes, and `diff`. Differences do not change the exit code from zero. Requires a local file. ## push ```sh theme={null} atonom push 42 --json atonom push order-total.lua --tool-id 42 --json ``` Uploads a local body. Linked changed files include their last synced hash; a remote conflict produces HTTP 409 and exit 1. `--force` omits that hash. Unlinked files have no synced hash to protect the first write. A file matching its last synced hash is treated as unchanged without fetching the remote. Push does not execute, enable, or change the schema of the tool. ## run ```sh theme={null} atonom run 42 --inputs '{"qty":2,"unit_price":12.5}' --json atonom run 42 --no-save --inputs-file fixtures/order.json --json ``` By default, saves the local file and then executes it through the platform test endpoint. The save request does not send an expected hash. `--no-save` omits the local body and executes the stored version; a numeric tool ID then works without a local file. `--inputs JSON` and `--inputs-file PATH` are mutually exclusive and must contain an object. The default is `{}`. Results include `status`, `value` or `error`, `saved`, `duration_ms`, `inputs`, and a hash when provided. A script failure exits 2 and does not undo a save. ## eval ```sh theme={null} atonom eval path/to/script.lua --transform '{"qty":2}' --json atonom eval -c 'return 42' --json printf 'return 42\n' | atonom eval - --json ``` Executes a Lua chunk in your configured sandbox. It does not read the tool manifest or require platform login. File paths are relative to the current directory. * `FILE` or `-`: a Lua file or stdin. * `--code LUA` / `-c LUA`: inline code; mutually exclusive with a file. * `--bindings JSON`: object whose keys are copied to Lua globals. * `--transform JSON`: bind `context` and append `return transform(context)`. * `--trap-result JSON`: next canned host response; repeat for successive calls. * `--trap-echo`: echo arguments for traps left after canned results. * `--max-traps N`: maximum traps to fulfill, default `16`. JSON output contains `outcome`, `traps`, `unanswered_trap`, and `exit_code`. Status values are `DONE`, `TRAP`, or `FAIL`. Resume tokens are stripped. A trap-limit result can have `outcome.status: "FAIL"` but exit code 3 because a call remains unanswered. ## Exit codes * **0:** success; inspect values and sync actions for the actual result. * **1:** command, configuration, auth, transport, or API error. * **2:** script failure from `run`/`eval`. CLI argument parsing also uses 2, so do not assume every code 2 contains a script result. * **3:** unanswered trap or eval trap limit. Errors are not guaranteed to be JSON. Capture stderr separately from machine-readable stdout. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.