Name: FlatRun
Author: FlatRun

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

Build from source:

make build
flatrun version
flatrun help

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

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

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.

FlatRun CLI