Skip to main content
Run atonom <command> --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

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.

​
config / status / 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

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

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

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

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

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

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

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

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.