Command-line guide

The atlas command checks the helper, observes its desktop and sends actions to apps there. Run it from your own account. This page helps you choose a command and interpret its result; the generated command reference lists every public command's exact options.

Find a command

atlas alone or atlas --help shows the command groups. Add --help at any level to read its options without performing the operation:

atlas --help
atlas screenshot --help
atlas agents install --help
atlas environment rollback --help

Get started

atlas agents status reports connections, and atlas agents status --brief gives a short session summary. install and remove accept host selectors. project DIR adds project instructions; forget DIR removes Atlas's sections. See the connection guide for the selectors and refresh steps.

--cursor selects the local Cursor connection. Its status checks registration files; verify actual loading in a fresh Cursor session. An owned Cursor registration can be removed even if the host has already been uninstalled.

Look at the helper

Use doctor to decide whether a task can start. Use the observation commands to decide what to do inside an app. A screenshot's pixels are not necessarily display points: the display point for pixel (px, py) is origin + pixel × pointsPerPixel, and origin is 0,0 for a full screenshot.

Act in the helper

Check the screen before acting, and verify the effect afterward. The daily use guide shows a complete open, inspect, act and close sequence. close --all is broader than closing the app you are testing: it includes ordinary app bundles and non-Apple menu bar apps, another agent's too, while leaving Atlas and macOS system apps alone.

run takes the program after --. The command starts in the helper's home. Quote a shell expression so that the helper's shell, rather than your own shell, expands its variables:

atlas run -- /bin/sh -c 'ls "$HOME/atlas-work"'

This example expects an atlas-work folder in the helper. A missing folder is a child-command failure. The default command timeout is 20 seconds; --timeout accepts 1 to 600 seconds. An agent keeps the timeout, plus any wait for its turn and about 10 seconds for Atlas to stop the command and send its output, under its host's shell time limit (see Agent connections). See Helper files and environment for tool paths and selected variables.

Prepare the helper

environment MANIFEST previews files. Its public subcommands are discover, profile, apply, list, rollback and run. See the environment guide before applying or undoing a plan. verify-native --fixture PATH is for a prepared native test session; see Contributing.

Take over or recover

Coordinate switching, locking and logging out with the person at the Mac. logout --force can discard unsaved work. Do not use recovery to repeat an action whose outcome is unknown. Follow Troubleshooting.

Look after Atlas

See Maintenance before updating, removing or repairing Atlas. See Configuration for settings selection and storage paths.

Global options and output

--config FILE selects a settings file and takes precedence over ATLAS_CONFIG. --json requests JSON output. Both are global options, so you can put them before or after a subcommand, but before the -- that begins a child command's arguments.

Ordinary command results are readable text in a terminal and JSON when redirected or piped. ATLAS_JSON can override that default; explicit --json wins. Help, version and atlas agents status --brief output are text, and atlas agent-guide prints Markdown. Interactive setup and commands that open a UI are not a stream of JSON results.

In JSON mode, each result is one line of JSON. A returned action result goes to stdout, including a result with ok: false. Command, configuration and connection errors go to stderr. On failure, read both streams. Do not assume an empty stdout means nothing happened. Every failure carries next, one sentence on what to do about it, and busy carries holder: person or agent. Commands that change the helper first wait up to 30 seconds for another Atlas command, in the order they began (--wait SECONDS or ATLAS_WAIT, up to 600, 0 for none), and busy then carries waited, the seconds waited. They never wait while the person has control or has stopped agents. busy names the agent session that has control in heldBy, focus-changed the session that last used the app in front in lastUsedBy, and the uncertain refusal says in yours whether the unknown action was this session's.

The process exits with status 0 for success, 1 for a failed result or execution error, and 2 for invalid command syntax. A command that changes the helper and is stopped by SIGTERM, SIGHUP or SIGINT exits with 128 plus the signal's number (143, 129 or 130), even when it printed its own result, and a failure it prints has the code interrupted. Two useful exceptions to treating ok as success are:

• doctor can return ok: true with ready: false, and exits 1.
• run can return ok: true because the child ran, but exits 1 if exitCode is nonzero or timedOut is true. Inspect those fields and the child's output.

For a script, capture both channels without retrying automatically. This read-only example keeps the doctor's output for inspection:

atlas_check_dir=$(mktemp -d)
if atlas doctor --json >"$atlas_check_dir/stdout.json" 2>"$atlas_check_dir/stderr.txt"; then
  cat "$atlas_check_dir/stdout.json"
else
  atlas_exit=$?
  cat "$atlas_check_dir/stdout.json" "$atlas_check_dir/stderr.txt" >&2
  printf 'Atlas exited with status %s\n' "$atlas_exit" >&2
fi
printf 'Check output: %s\n' "$atlas_check_dir"

Inspect the result before deciding what to do next. An uncertain: true error means the action may have happened. Preserve its evidence, observe if possible and follow the recovery steps.