The CLI

The Amolfi CLI is the terminal client of the API. It reads your workspace, 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 dedicated browser authorization page
amolfi login --manual    # print the fallback URL and one-time code
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 sessions                        # the session rail, pinned first
amolfi sessions start "close the books for July"
amolfi sessions events <session_id> --after 12
amolfi sessions fork <session_id> 42 --title "What if we delay"

amolfi ask "draft the october email from what actually shipped"   # Auto + Normal
amolfi ask --style collaborative "shape the launch with me"      # Ask
amolfi ask --effort ultrawork "audit the launch and finish it"
amolfi runs                            # recent durable work, current first
amolfi runs start --style collaborative --effort high "<goal>"
amolfi runs select <run_id>            # share the selection across terminals
amolfi runs status                     # inspect the selected run
amolfi runs watch [run_id]             # follow selected or explicit work
amolfi runs guidance <run_id> "shorter, warmer"
amolfi runs cancel [run_id]
amolfi runs clear

Add --json to any read for the raw payload. ask is the everyday verb and starts an Auto run at Normal effort by default. In the interactive shell, Shift+Tab or /style opens Ask and Auto; /effort opens Fast, Normal, High, and Ultrawork. Auto returns the run id and lets Amo continue in the background; Ask follows the run and pauses only when your judgment would materially improve the result. The shell session is only the terminal view; working style and effort remain durable server-side state and can be read from another terminal.

Each read needs its catalog scope: for example, team needs workspace.team.read, while run discovery and status need runs.runs.read. A missing scope returns SCOPE_REQUIRED rather than an empty result 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