Developer CLI

Create Actions, wait for typed human decisions, manage Watches, and wrap scheduled jobs with the ActionBox CLI.

The actionbox CLI lets scripts, CI jobs, scheduled tasks, and agents ask a human for a decision and continue when the answer arrives.

Install

The CLI is publicly available from PyPI as platform-specific wheels for macOS, Linux, and Windows on AMD64 and ARM64. Python 3.9 or newer is required to install the wheel; the ActionBox command itself is a prebuilt binary and does not require Go.

python -m pip install actionbox
actionbox version

Create a Source in the ActionBox dashboard, then configure and verify the CLI:

actionbox configure
actionbox doctor

Interactive token entry is hidden. For CI or another non-interactive runner, pipe the Source token through standard input so it does not appear in the process arguments:

printf '%s\n' "$ACTIONBOX_API_KEY" | actionbox configure --token-stdin
actionbox doctor

ACTIONBOX_CONFIG_FILE selects an isolated configuration file when a runner should not use the default user-level path. The defaults are:

macOS: ~/Library/Application Support/actionbox/config.json
Linux: ${XDG_CONFIG_HOME:-$HOME/.config}/actionbox/config.json
Windows: %AppData%\actionbox\config.json

On Unix-like systems, the CLI writes the directory for the current user and the file with 0600 permissions. It rejects symbolic-link and group- or world-readable configuration files.

Ask and wait

actionbox ask "Deploy to production?" \
  --assignee-email reviewer@example.com \
  --option approve="Approve deployment" \
  --option reject="Reject deployment" \
  --wait \
  --timeout 30m \
  --json

ask requires at least one --option or an --interaction-json object. Use id=Label to keep option IDs stable.

Important options include:

Option	Purpose
`--description TEXT`	Add review context.
`--priority LEVEL`	`low`, `normal`, `high`, or `urgent`.
`--assignee-email EMAIL`	Route to an active reviewer in the Source workspace.
`--assignee-user-id ID`	Route using the stable ID copied from Settings → Team.
`--private`	Restrict a Team Action to named reviewers and managers.
`--reviewer-email EMAIL`	Add an allowed reviewer; repeat for up to 15 reviewers.
`--reviewer-user-id ID`	Add an allowed reviewer by stable ID; repeat for up to 15 reviewers.
`--approval-mode MODE`	Require `any`, `all`, or `quorum` approval; also requires `--private` and explicit reviewers.
`--required-approvals N`	Set the threshold for `quorum`.
`--approval-option-id ID`	Map the approving option for a two-option policy.
`--rejection-option-id ID`	Map the rejecting option for a two-option policy.
`--allow-source-override`	Permit a later explicit, reasoned Source override.
`--option VALUE`	Repeat up to three times; accepts `id=Label`.
`--interaction-json JSON	@FILE`
`--context-json JSON	@FILE`
`--decision-class VALUE`	Attach a stable category for a Decision Brief.
`--decision-context-json JSON	@FILE`
`--on-expire-json JSON	@FILE`
`--callback-url URL`	Send terminal state to a public HTTPS callback.
`--context-request-mode MODE`	Allow reviewer follow-ups through `poll` or `callback`; defaults to `unsupported`.
`--dedupe-key KEY`	Merge repeated open occurrences.
`--expires RFC3339`	Set server-side expiration.
`--no-origin`	Do not attach automatically detected CI origin metadata.
`--wait`	Wait until terminal state or local timeout.
`--timeout DURATION`	Maximum local wait; defaults to one hour.
`--json`	Print the structured result.
`--quiet`	Print only the selected option while waiting.

The assignment flags are optional and mutually exclusive. Email matching is case-insensitive. A reviewer outside the Source workspace, an inactive member, or a viewer is rejected. Omit both flags to use the workspace default reviewer or normal plan routing.

For a restricted Action, add --private and repeat either reviewer flag. Do not mix reviewer emails and reviewer IDs. A single assignee may be used instead when only one person should have review access.

For an opted-in Approval Policy, use actionbox resolve ACTION_ID --approval-override --reason "…" with an option or typed response. Normal Source resolution cannot bypass reviewer votes. See Approval Policies.

@FILE inputs are limited to 256 KiB. Absolute paths are supported for CI and temporary files; only reference JSON that you intend to send to ActionBox.

A terminal Action prints a descriptive result and returns normally; add --quiet for only the selected option. A local wait timeout exits 124 and leaves the Action open; Ctrl+C exits 130 and also leaves it open. API, network, or validation errors exit 1.

CI origin metadata

In recognized GitHub Actions, GitLab CI, Jenkins, and CircleCI environments, the CLI automatically adds bounded origin metadata to the Action. Depending on the provider, this can include a workflow or job reference, repository and branch labels, a shortened commit identifier, and a build URL. This makes the request easier for a reviewer to verify, but private repository names and CI URLs may be sensitive. Add --no-origin to send or ask when that context should not leave the runner.

Branch on the decision value

Do not interpret every successful process exit as approval. Read the selected option or parse the JSON decision or typed response field.

Other commands

actionbox send TITLE
actionbox get ACTION_ID
actionbox resolve ACTION_ID
actionbox cancel ACTION_ID
actionbox watch create|list|pause|resume|rotate-token|archive
ACTIONBOX_WATCH_URL=URL actionbox run -- COMMAND
actionbox mcp

--watch-url URL remains available, but the environment variable avoids placing the bearer capability in shell history or the Actionbox process arguments. Run actionbox COMMAND --help for the exact options shipped with your installed version. Keep Source tokens and Watch capability URLs out of logs, browser code, and source control.

Update

python -m pip install --upgrade actionbox
actionbox version

Uninstall

Before removing the CLI, record the configuration path if you also want to delete the saved Source token:

actionbox doctor --json
python -m pip uninstall actionbox

The uninstall command removes the CLI package. It does not delete the config_file reported by actionbox doctor --json, and it does not revoke the Source. Delete that exact file if the machine should no longer retain the token. The default locations are listed in Install.

Revoke or rotate the Source from the ActionBox dashboard when this machine or integration should no longer be trusted. Removing the package or its local configuration cannot invalidate a token that may have been copied elsewhere.