FlatRun CLI - FlatRun Docs

flatrun is the command-line interface for FlatRun. It is the automation and operator surface for the platform, the same way a cloud CLI wraps a larger API. Anything you do in the UI you can script from the CLI, and anything the CLI does not yet wrap is reachable through its raw API bridge.

Install

Install the latest release on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/flatrun/cli/main/scripts/install.sh | sudo sh
flatrun version

The installer detects amd64 or arm64 and verifies the release archive against its published SHA-256 checksum before installing flatrun in /usr/local/bin.

Choose a version or destination

curl -fsSL https://raw.githubusercontent.com/flatrun/cli/main/scripts/install.sh \
  | sudo FLATRUN_VERSION=0.3.0 INSTALL_DIR=/opt/flatrun/bin sh

In CI, install a pinned release with the setup-flatrun GitHub Action instead of building.

Update

Update the installed binary to the latest release:

sudo flatrun update

sudo is needed when flatrun is installed in a system directory such as /usr/local/bin. An installation owned by your user can be updated without it.

Check whether an update is available without changing the installed binary:

flatrun update --check

Release channel. Stable builds follow stable releases. Prerelease builds follow the newest published release, including later prereleases. The updater verifies the archive against the release's published SHA-256 checksum before replacing the current binary.

Connect to a Server

For local operator work, save a named profile:

flatrun configure set --profile prod --url https://panel.example.com --token TOKEN
flatrun configure use prod
flatrun configure list

Tokens can be read from stdin so they never land in shell history:

printf '%s' "$FLATRUN_TOKEN" | flatrun configure set --profile prod \
  --url https://panel.example.com --token-stdin

Where config lives. Profiles are stored at ~/.flatrun/config.json (directory 0700, file 0600). Override the path with FLATRUN_CONFIG. Use --profile NAME to run a single command against a different server without switching the active profile.

Environment Variables

Variable	Purpose
`FLATRUN_URL`	API URL (skips needing a profile)
`FLATRUN_TOKEN`	API token
`FLATRUN_PROFILE`	Select a saved profile
`FLATRUN_CONFIG`	Override the config file path

In CI, prefer environment variables over a profile (see CLI in CI/CD).

Global Options

Option	Purpose
`--profile NAME`	Use a named profile
`--url URL`	Override the API URL
`--token TOKEN`	Override the API token
`--timeout DURATION`	Request timeout
`--insecure-skip-verify`	Skip TLS verification
`--json`	Print raw JSON instead of friendly output
`--verbose`	Print request/response diagnostics to stderr (never the token)

Check Connectivity

flatrun health
flatrun deployment list

Learn an Operation

The CLI reads request types and constraints from the connected agent. Help for an operation shows its fields, required values, accepted values, permission, query parameters, and plan support.

flatrun deployments create --help
flatrun deployments create --generate-cli-skeleton

The skeleton is JSON. Save it, fill in the values, and send it with --data @request.json.

flatrun deployments create --data @request.json

Version check. Saving a profile reports both the agent and CLI versions. The CLI warns when it is newer than the connected agent, since newer commands may not exist there yet.

Plan Before Apply

Use --plan on a supported operation. It returns the exact resources and files that would change without changing them.

flatrun deployments delete staging --plan \
  -q delete_ssl=true \
  -q delete_database=true \
  -q delete_vhost=true

Apply the reviewed plan by its id:

flatrun plans apply PLAN_ID

See Plan & Apply for drift checks, expiry, and required-plan deployments.

Deployments

Create a deployment straight from an image:

flatrun deployment create my-api \
  --image ghcr.io/acme/api:main \
  --port 8080 \
  --host-port 18080

Inspect and operate an existing deployment:

flatrun deployment info my-api
flatrun deployment images my-api      # service-to-image mapping
flatrun deployment services my-api
flatrun deployment containers my-api
flatrun deployment pull my-api --only-latest
flatrun deployment restart my-api
flatrun deployment rebuild my-api
flatrun deployment stop my-api
flatrun deployment delete my-api --confirm my-api

Update a Single Service Image

For compose-based deployments, update one service's image and write the compose back. Add --deploy to pull and run an operation in the same command:

flatrun deployment image set my-api app ghcr.io/acme/api:sha-abc123
flatrun deployment image set my-api app ghcr.io/acme/api:sha-abc123 --deploy --operation restart

Deploy vs. image set. deployment deploy pulls first by default and runs an operation, which suits compose that already references a moving tag like latest. deployment image set pins a specific service to a specific image (ideal for immutable SHA tags from CI).

Images & Containers

flatrun image list
flatrun image pull ghcr.io/acme/api:sha-abc123 --credential-id cred_123
flatrun image delete IMAGE_ID

flatrun container list
flatrun container restart CONTAINER_ID
flatrun container stop CONTAINER_ID

Raw API Bridge

Call any backend endpoint directly while a polished command is still pending. The path may include or omit the /api prefix.

flatrun api get /settings
flatrun api get /users
flatrun api post /databases/list --data '{"container":"mysql"}'

See the API reference for available endpoints.