The CLI

The Amolfi CLI is the terminal client of the API. It reads your workspace, uploads scan-gated Files, hands Amo goals, and follows runs. Anything that sends, spends, signs, publishes, or otherwise needs an owner still stops for approval.

npm install -g @amolfi/cli

It needs Node 20 or newer and has no runtime dependencies. It is proprietary software, licensed for use with the Amolfi service.

Sign in

amolfi login      # opens the device flow — approve in the browser, pick the workspace
amolfi logout     # clear the stored credential

The credential lives in your operating system’s credential store, never in a dotfile. For unattended use — CI, cron, a scheduler — skip sign-in and export a workspace token instead:

export AMOLFI_TOKEN=amolfi_sk_…       # minted in Settings → API keys
export AMOLFI_API_URL=https://…       # optional; defaults to https://api.amolfi.com

The verbs

amolfi health                          # liveness — no credential needed
amolfi scopes                          # the public scope catalog

amolfi team                            # roster and roles — who can approve
amolfi webhooks                        # registered endpoints
amolfi audit 50                        # the workspace audit log
amolfi files list                      # ordinary Files metadata
amolfi files put ./pricing-model.md    # upload and wait for scanning
amolfi files get <id> --output ./copy.md

amolfi ask "draft the october email from what actually shipped"
amolfi runs start "<goal>"             # start it, print the id, return
amolfi runs get <run_id>               # one snapshot
amolfi runs watch <run_id>             # follow until it finishes or needs an owner
amolfi runs guidance <run_id> "shorter, warmer"
amolfi runs cancel <run_id>

Add --json to any read for the raw payload. ask is the everyday verb — it starts a run and follows it in one step.

The reads need their scope on the token — a token without workspace.team.read gets a clear SCOPE_REQUIRED rather than an empty table that looks like an empty workspace.

What the CLI deliberately cannot do

There is no verb to mint or revoke a key, invite or change a member, or connect a provider — and no approve verb. A pending approval prints the exact approval URL and never opens a browser; you go and read the card yourself. The scope that would let a terminal approve does not exist, which is the design, not a gap.

Exit codes

• 0 — fine, including a run that is waiting on an owner. Waiting is the designed outcome, not a failure.
• 1 — an API or network error.
• 2 — a usage or configuration mistake.

AuthenticationRuns