CLI

The appstrate CLI installs and operates an instance, signs you in to any instance, and drives its API from a terminal or a script. It is a single self-contained binary: no Node.js or other runtime is required on the host (except Bun for a Tier 0 install). This page covers the common cases. The full flag tables are in the CLI README.

Global flags work on every command: -p, --profile <name> selects a profile, --insecure allows an instance without HTTPS (tokens then travel in plaintext, so use it on a trusted network only), and --version prints the version.

Get the CLI

curl -fsSL https://get.appstrate.dev | bash

bun install -g appstrate     # needs Bun 1.3.9 or later
bunx appstrate <command>     # or run it once without installing

The two channels are independent. If both are installed, appstrate doctor lists every appstrate on your PATH and which one wins. See Upgrading the CLI.

Driving the CLI from a coding agent

The repository ships an operating manual written for a coding agent: apps/cli/AGENTS.md. It covers the zero-to-first-run recipe, the rules of engagement and a curl to appstrate api cheat sheet. With a logged-in profile the CLI injects the bearer token itself, so the agent never sees it. An API key passed through the environment or --api-key is readable by the process that sets it, so give an agent a key scoped to what it may do. See also Skills and coding agents.

Commands

Headless and CI runs

appstrate run can authenticate without appstrate login: give it an API key and the instance, and it works on a CI runner or any machine with no profile. appstrate api reads the same key and instance (see Call the API with an API key). The other commands (openapi, whoami) still need a profile.

With an API key, the organization and the space come only from APPSTRATE_ORG_ID and APPSTRATE_SPACE_ID, never from the active profile: a key is pinned to one organization and one space. X-Org-Id is ignored with an API key (the key is bound to its organization); only X-Space-Id is checked, and one that disagrees with the key is answered with 403. Leave both unset for a platform run, and when you set them, set the ones the key is pinned to. An empty value counts as unset. Only the instance falls back to the profile. If you upgrade the CLI and a job used to rely on the profile's space, it now needs APPSTRATE_SPACE_ID, or stops with the message No space id for a local run.

The key needs a few scopes, depending on what you run:

The last two are described under Remote runs. Mint the key with the narrowest list that covers your case.

Call the API with an API key

For a CI job or a script on a machine with no login, pass an apst_ API key instead of a session:

export APPSTRATE_API_KEY=apst_...
export APPSTRATE_INSTANCE=https://appstrate.example.com   # optional when a profile exists
appstrate api GET /api/agents

• The key replaces the profile credential entirely. The keyring is not read and no profile is needed. --api-key <key> does the same as the variable and wins over it, but a command-line argument is visible to other local users, so prefer the variable. An empty --api-key is refused. Leading and trailing whitespace is trimmed, and a key that still contains whitespace, a line break or a non-ASCII character is refused.
• The instance is APPSTRATE_INSTANCE, else the profile's. With neither, the command stops.
• No X-Org-Id or X-Space-Id is sent: a key is pinned to one organization and one space, and those apply. Your own -H headers still pass through.
• An exported APPSTRATE_API_KEY switches every appstrate api call to the key. If that variable is already set for appstrate run, api in the same shell stops using your login: another principal, no org or space headers, and the instance APPSTRATE_INSTANCE names. Unset it to go back to your profile.
• Only api and run read the key. openapi, whoami and the other commands still use the profile.

Platform run or remote run

The two words name two different things, and the CLI flag --remote selects the first one.

• A platform run executes on the instance, in its sandbox, as if you had clicked Run in the dashboard. It is the default for a package id, and --remote selects it explicitly.
• A remote run (runOrigin: "remote") executes on your own host, in the appstrate process, with your shell, filesystem and environment. It is what you get with --local or with a bundle path. When the run has credentials for an instance, the CLI also registers it and streams signed events back, so it shows up in the dashboard with a Remote badge. See Runs.

Use a platform run when the agent should behave exactly as it does in the dashboard: same sandbox, model, connections and stored run configuration. A CI step that triggers a production agent and waits for its result is the typical case. Use a remote run when the agent has to act on the machine that runs the CLI (the files of a checkout, local tools), when it must use your own LLM key, or while you iterate on a bundle with --snapshot.

One limit of a remote run: only serverless apiCall integrations are available in-process, since MCP-server integrations are skipped.

Flags of a remote run

--model-source preset reads the list of presets with GET /api/models, using the session of a CLI profile, not the API key. So preset mode needs appstrate login on that machine even when APPSTRATE_API_KEY is set. A job that has only an API key must pass --model-source env, since preset is the automatic choice for a package id, or call the LLM proxy itself.

When you run a package id with --local, the CLI also reads the space's run configuration for that agent (model, generation settings, stored input values) and applies it under your flags. Pass --no-inherit in CI so that a change made in the dashboard cannot alter a pipeline.

CI examples

A GitHub Actions job that triggers an agent on the instance and fails when the run does:

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - name: Install the CLI
        run: |
          curl -fsSL https://get.appstrate.dev | APPSTRATE_NO_LAUNCH=1 bash
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Run the agent on the instance
        env:
          APPSTRATE_API_KEY: ${{ secrets.APPSTRATE_API_KEY }}
          APPSTRATE_INSTANCE: https://appstrate.example.com
        run: |
          appstrate run @acme/triage \
            --input-file ./input.json \
            --run-id "ci-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" \
            --json --output result.json

The key needs agents:run and runs:read. It names its own organization and space, so no APPSTRATE_SPACE_ID is set. With --json the CLI prints events as JSON lines, starting with an appstrate.remote.triggered line that carries the run id, and the step ends with exit code 1 when the run did not succeed. If the CLI receives SIGINT, SIGTERM or SIGHUP while the run is in flight, it detaches and the run carries on on the instance.

The same job as a remote run on the runner itself, with your own model key:

- name: Run the agent on this runner
  env:
    APPSTRATE_API_KEY: ${{ secrets.APPSTRATE_API_KEY }}
    APPSTRATE_INSTANCE: https://appstrate.example.com
    APPSTRATE_SPACE_ID: spc_xxx
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    appstrate run @acme/triage --local \
      --model-source env --no-inherit \
      --input-file ./input.json \
      --output result.json

This one needs APPSTRATE_SPACE_ID, set to the space the key is pinned to, because a run on your host names the space when it registers itself and calls the credential proxy. The key needs agents:read and agents:run, plus skills:read if the agent depends on a skill and credential-proxy:call if it uses integrations. The run is reported to the instance and appears there as a remote run. Do not rely on the exit code to detect a failed agent: read status in result.json.

Profiles

A profile ties a name to an instance URL, your identity and the pinned organization and space. The active profile is the first of: the --profile flag, the APPSTRATE_PROFILE environment variable, defaultProfile in the config file, then default.

appstrate login --profile prod --instance https://appstrate.acme.com
appstrate --profile prod whoami
APPSTRATE_PROFILE=prod appstrate api GET /api/agents

Profiles live in ~/.config/appstrate/config.toml (or under $XDG_CONFIG_HOME). Tokens are stored in the OS keyring (macOS Keychain, libsecret, Windows Credential Manager) under the profile's name. If no keyring backend exists at all, for example in a headless Linux container, the CLI falls back to a 0600 file ~/.config/appstrate/credentials.json. If a keyring exists but refuses access (locked), the CLI stops unless you set APPSTRATE_ALLOW_PLAINTEXT_TOKENS=1. On Windows there is no file fallback.

Troubleshooting

More entries are in the CLI README.

Reference

• CLI README: every flag, exit code and edge case.
• REST API.