Interfaces

The Apprail CLI

Small, composable commands for your terminal, CI, and coding agents. Every command talks to the same API as the console.

Install and sign in

macOS and Linux

curl -fsSL https://console.apprail.io/api/cli/install.sh | sh
apprail login

The installer checks the download’s checksum and puts apprail in ~/.local/bin, without sudo. On Windows, download apprail-windows-amd64.exe from https://console.apprail.io/api/cli/. apprail login asks for a token created in the console under Settings → API tokens.

Conventions

Services are PROJECT/SERVICE, where PROJECT is a slug or ID.
Commands act on production unless you pass --env NAME.
Deploys, builds, promotions, and rollbacks follow progress until the release is live or fails; --detach returns at once.
Deleting a database, cache, queue, or bucket needs --confirm NAME.
Run any command without arguments, or apprail help, for its usage.

In CI

Skip login: set APPRAIL_TOKEN to a service account’s CI token with Deploy access, so the pipeline keeps working when people come and go. APPRAIL_API_URL overrides the API address.

GitHub Actions

- run: curl -fsSL https://console.apprail.io/api/cli/install.sh | sh
- run: ~/.local/bin/apprail deploy shop/web --image ghcr.io/acme/web:${{ github.sha }}
  env:
    APPRAIL_TOKEN: ${{ secrets.APPRAIL_TOKEN }}

In a protected environment, the deploy waits for approval and the step blocks until someone decides.

Account and workspace

Command	What it does
`apprail login [--api URL]`	Store an API token created in the console
`apprail logout`	Forget the stored token on this machine
`apprail whoami`	The signed-in account and workspace
`apprail members`	List members; also invite EMAIL [--role …] \| role EMAIL ROLE \| remove EMAIL
`apprail service-accounts`	Service accounts for CI and automation, and their tokens (created in the console)
`apprail usage [--month YYYY-MM] [--projects]`	This month’s usage and your workspace limits
`apprail activity [--by agent] [--action PREFIX] [--search TEXT] [--since DATE] [--until DATE] [--csv]`	Audit history, filterable and exportable
`apprail export > workspace.json`	The workspace’s configuration as JSON (no secrets)
`apprail registries`	Private registry credentials; also add \| rotate \| delete
`apprail alerts`	Alert channels; also add NAME --kind slack\|discord\|webhook \| test \| remove

Manifest and agents

Command	What it does
`apprail capabilities [--json]`	What this platform supports right now
`apprail mcp [--read-only]`	Run the MCP server for coding agents
`apprail version`	The CLI’s version
`apprail init [--name NAME] [--git URL \| --image IMAGE]`	Write a starter apprail.yml
`apprail inspect [--file PATH] [--json]`	Validate apprail.yml and show it with defaults
`apprail plan [--file PATH] [--json]`	Compare apprail.yml with your workspace, read-only

Projects, environments, and services

Command	What it does
`apprail projects`	List projects; also create NAME [--slug SLUG] \| delete PROJECT
`apprail envs PROJECT`	List environments
`apprail services PROJECT`	List services
`apprail services create PROJECT NAME --port PORT [--health PATH]`	A web service (or --worker for a background worker)
`apprail services update PROJECT/SERVICE … [--apply ENV]`	Port, health path, CPU, memory, instances, autoscaling on CPU or a queue (--scale-queue), canary or blue/green, sleep when idle (--sleep-after), pre-deploy command; --apply ENV on its own redeploys what’s live
`apprail services delete PROJECT/SERVICE`	Remove a service and everything it runs
`apprail status PROJECT/SERVICE`	Addresses, what is live, recent deployments

Deploying

Command	What it does
`apprail deploy PROJECT/SERVICE --image IMAGE [--env NAME]`	Deploy a container image
`apprail build PROJECT/SERVICE --git URL [--ref REF] [--context DIR]`	Build from a Git repository and deploy
`apprail build PROJECT/SERVICE --rebuild`	Rebuild the linked GitHub branch now, no push needed
`apprail promote PROJECT/SERVICE --from staging --to production`	Deploy the exact release from one environment to another
`apprail promote PROJECT --from staging --to production`	Promote every service whose live release differs, together, with rollback if one fails
`apprail release PROJECT --env ENV SVC=IMAGE[,SVC=IMAGE] …`	Deploy several services in stages; each stage starts once the previous one is live (--no-rollback)
`apprail releases PROJECT [--cancel RELEASE]`	Recent multi-service releases and what happened to each service
`apprail rollback PROJECT/SERVICE [--to DEPLOYMENT]`	Go back to a release that was live before
`apprail domains PROJECT/SERVICE`	Custom domains; also add HOSTNAME [--env NAME] \| delete HOSTNAME

Running and debugging

Command	What it does
`apprail logs PROJECT/SERVICE [--tail N] [-f]`	Runtime logs, live
`apprail diagnose PROJECT/SERVICE [--json]`	Why a service is unhealthy, and what to do
`apprail metrics PROJECT/SERVICE [--json]`	CPU and memory per instance
`apprail traffic PROJECT/SERVICE [--range 24h\|7d\|30d] [--json]`	Requests, errors, bandwidth, and top countries and pages at the edge
`apprail run PROJECT/SERVICE -- COMMAND`	Run a one-off command in the live release, output streamed
`apprail jobs PROJECT/SERVICE`	Jobs; also create \| run \| runs \| logs RUN_ID \| cancel RUN_ID \| delete
`apprail uptime PROJECT/SERVICE`	Uptime checks; also on [--path …] [--interval …] [--threshold …] \| off

Data and configuration

Command	What it does
`apprail variables PROJECT [--values \| --dotenv]`	Your variables and the ones Apprail sets
`apprail variables set PROJECT KEY=VALUE…`	Set variables (VALUE - reads from standard input); unset PROJECT KEY…
`apprail databases PROJECT`	Postgres; also create \| show \| connect \| backup \| backups \| restore \| rotate-password \| delete
`apprail caches PROJECT`	Valkey caches; also create \| rotate-password \| delete
`apprail queues PROJECT`	RabbitMQ queues; also create \| rotate-password \| delete
`apprail buckets PROJECT`	S3-compatible buckets; also create \| rotate-key \| delete

Everyday examples

Deploy, watch, and debug

apprail deploy shop/web --image ghcr.io/acme/web:1.4
apprail logs shop/web -f
apprail diagnose shop/web
apprail run shop/web -- npx prisma db seed

Scale and release safely

apprail services update shop/web --instances 2 --max-instances 6 --target-cpu 70 --apply production
apprail services update shop/web --canary 10 --canary-minutes 10
apprail services update shop/web --blue-green on
apprail services update shop/web --pre-deploy "npx prisma migrate deploy"

capabilities, inspect, plan, metrics, and diagnose take --json for machine-readable output. apprail run exits with the command’s own exit code, and diagnose exits with 2 when a service is failing, so both work in scripts.