CLI command reference

The upstate command runs on your workstation. It connects an existing Kamal application and reads evidence from Upstate. It does not provide a hosted shell or remotely control your servers. The separate upstate-agent runs on Linux hosts and reports observations.

Install with brew install upstate-run/tap/upstate or use the verified CLI release archive. Run upstate version to check the installed CLI. Commands below describe functionality in the current released code; an older installed binary may support fewer options.

Start in an existing Kamal repository

upstate connect --dry-run
upstate connect
upstate status
upstate doctor
upstate kamal deploy
upstate receipt --watch

The connection creates safe project mappings and managed lifecycle hooks. A host observer is needed for independent verification. The connection is not a deployment: upstate connect does not deploy your application.

For the entire deployment workflow, including migration and custom image considerations, read Deploying with Kamal.

Command directory

upstate hook pre-deploy, upstate hook post-deploy, and credential lookups are internal integration commands: the generated hooks use them. Do not add them as manual deploy steps.

Connect and reconnect options

upstate connect --help
upstate connect --dry-run
upstate connect --destination production
upstate connect --config config/deploy.edge.yml
upstate connect --project "My project"
upstate connect --url https://app.example.com
upstate connect --observer systemd
upstate connect --observer kamal
upstate connect --observer manual
upstate connect --configure-only
upstate connect --hooks-only
upstate connect --host 192.0.2.10=host_example

• --dry-run reads static configuration and prints a plan. It does not authenticate or make changes.
• --destination NAME limits the operation to one Kamal destination; --config PATH chooses another base config inside the repository. Multiple services may need separate --config calls.

• --project NAME|ID picks or creates the project by name; use it deliberately when moving an existing environment between projects.

• --url URL is your application's public HTTP URL, not the Upstate server. --upstate-url ORIGIN or UPSTATE_URL changes the Upstate origin, normally unnecessary.

• --observer systemd|kamal|manual chooses the installation method. In noninteractive mode without this choice, observers are left unchanged.

• --configure-only writes integration files without booting observers. --hooks-only sets up only project mapping and hooks for a service already monitored elsewhere; it does not edit Kamal YAML, host records or observers.
• --host ADDRESS=host_... associates a Kamal address with an existing Upstate server. --new-host ADDRESS explicitly creates one. Connect does not silently manufacture a server for an unmatched address.

• --account NAME|ID chooses a saved account; --yes confirms proposed changes; --ssh-user USER overrides the observer-install SSH user.

• For configs requiring ERB or dynamic values, use --service NAME and --targets ROLE@HOST,... rather than asking Upstate to execute the configuration.

Review every proposed diff. Existing pre/post-deploy hooks are preserved and invoked by the managed wrappers. Reconnecting an existing project should not replace working observers or duplicate resources. See The host observer.

Inspect production and use JSON

upstate status
upstate status --json
upstate status --all
upstate status --all --json
upstate status --all-accounts --json
upstate receipt
upstate receipt --json
upstate receipt --id dep_example --watch
upstate doctor
upstate doctor --json
upstate open
upstate open --receipt
upstate open --alerts

Use --json when a script or coding agent needs structured data. status --all works outside a project and includes watched components, running instance counts, the latest receipt, open alerts and discovered but unwatched components. --all-accounts uses saved account logins and reports account-specific failures without stopping the other account reads.

receipt --watch polls Upstate for a terminal outcome; it does not wait for Kamal to exit or deploy the image. Without --id, it reads the latest receipt for the checkout's saved .upstate app/environment mapping. A preceding upstate kamal deploy -d NAME or -c PATH does not change that mapping for the next command. For another service or destination, obtain the receipt ID (dep_...) from that deployment's Upstate page or receipt link and run upstate receipt --id dep_example --watch; use upstate logs dep_example to inspect that same deployment's logs. Do not treat an older Verified receipt as proof of a different deployment. Read Deployment receipts for the meanings of Verified, Needs attention, Incomplete and Superseded.

Run Kamal and investigate a receipt

upstate kamal deploy
upstate kamal redeploy -d production
upstate kamal app details -d production
upstate kamal proxy details
upstate kamal accessory details
upstate receipt --json
upstate run dep_example.1
upstate logs
upstate logs dep_example --lines 100 --since 15m
upstate logs --follow
upstate hook flush

upstate kamal uses the repository's executable bin/kamal when present, otherwise the kamal on your PATH. It passes your options, terminal input/output, signals and Kamal's exit code through. Upstate connectivity problems do not cancel Kamal. Managed hooks send exact lifecycle versions; without hooks the wrapper can use an explicit --version, VERSION or a clean Git HEAD. A dirty checkout without managed hooks cannot safely establish its eventual version.

deploy, redeploy and rollback use lifecycle reports through managed hooks or the no-hooks fallback; they do not also create a separate Kamal command-activity record or details-facts record. For non-lifecycle commands, the wrapper reports bounded activity metadata: command name, timestamps, exit code, CLI version, and the selected config path (-c) and destination (-d) when provided. Those two identifiers are uploaded as metadata; arbitrary other argument values, environment variables and raw terminal output are not uploaded. For app details, proxy details and accessory details, it can additionally parse and upload an allowlist of facts locally. UPSTATE_KAMAL_FACTS=off disables only this optional facts capture/upload, not the activity metadata (including -c and -d). Avoid putting sensitive information in config paths or destination names. Failed lifecycle sends can be retried with upstate hook flush.

upstate run accepts only receipt-provided suggestions for selected Kamal command families and confirms commands that change production, unless you pass --yes. It is not a general shell interpreter. upstate logs executes Kamal locally with the receipt's project, destination, roles and hosts; it is different from opt-in stored log snapshots.

Watch events

upstate watch
upstate watch --json
upstate watch --notify
upstate watch --all-accounts

Watch starts with new events rather than replaying the entire history. It follows deploy start/finish and alert open/clear. --json writes one structured event per line; --notify opts into desktop notifications on supported macOS and Linux environments. Stop with Ctrl-C.

Manage observers

upstate observer status
upstate observer upgrade --host prod-01
upstate observer upgrade --dry-run
upstate observer switch --to systemd --host prod-01
upstate observer switch --to kamal --host prod-01
upstate observer remove --host prod-01

Changes show the plan and require confirmation. upgrade pins to the version supported by your CLI. switch verifies the replacement observer reports before offering to remove the former one. remove --retire can also retire the server's Upstate record and revoke credentials. Select --config and --destination explicitly when several services are present; management commands refuse to guess on ambiguous targets.

For systemd installs, passwordless sudo is not mandatory: the CLI can stage a verified binary and one root-run script on the server and tell you exactly what to execute. Review the staged command and wait for the first fresh host report. See The host observer.

Authentication and saved accounts

upstate auth login
upstate auth whoami
upstate account list
upstate account use "My account"
upstate auth logout
upstate mcp --help

The browser-approved human session and each host/hook token are different credentials. Sessions and machine credentials are stored in protected user configuration files outside the repository; .upstate/*.json contains safe project identifiers and is suitable for source control. auth logout revokes and removes the selected human session, not every observer or coding-agent grant. Use Coding agents for MCP approval and revocation.

Production audit

upstate audit --local
upstate audit --json
upstate audit --destination production
upstate audit --hosts
upstate audit --hosts --no-upload
upstate audit --local --prompt

--local needs no login and does not upload configuration findings. --hosts uses consented read-only SSH inspection from your workstation, not an Upstate server command. --no-upload keeps host and configuration results local; --prompt produces a sanitized agent handoff. See Production audit.

What to do when a command fails

Start with upstate doctor, upstate auth whoami, your current working directory, the selected destination and the observer's last report. An unreachable Upstate service may prevent status and receipt reads, but it does not establish that Kamal or your application is down. See Troubleshooting.