FlatRun CLI

flatrun is the command-line interface for FlatRun. It is intended to be the automation and operator surface for FlatRun in the same way cloud CLIs wrap a larger platform API.

Install from source

make build

Quality Checks

make fmt-check
make vet
make test
make qa

CI runs formatting, vet, tests, golangci-lint, and multi-platform builds for Linux and macOS on amd64/arm64.

Releases

Releases are created from the GitHub Actions Release workflow. Before running it:

1. Update VERSION.
2. Add the matching entry to CHANGELOG.md.
3. Run the workflow manually with the same version value.

The workflow validates that the input version, VERSION, and CHANGELOG.md agree before calling whilesmart/workflows/go/release@main.

Configuration

Use environment variables in CI:

export FLATRUN_URL=https://panel.example.com
export FLATRUN_TOKEN=fr_xxx

Or configure a local profile:

flatrun configure set --url https://panel.example.com --token fr_xxx
flatrun configure list

Config is stored at ~/.flatrun/config.json by default. Use FLATRUN_CONFIG to override the path.

Commands

Deploy an existing app from CI by pulling images and then applying a runtime operation:

flatrun deployment deploy my-app --operation restart --json

Create a deployment directly from an image:

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

Manage an existing deployment:

flatrun deployment info my-api
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
flatrun deployment images my-api
flatrun deployment containers my-api
flatrun deployment services 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

deployment pull operates at deployment level and may pull multiple images because a deployment can contain multiple compose services and containers. Use deployment images to inspect the service-to-image mapping first.

deployment image set updates the image for one compose service and writes the updated compose back to the deployment. Add --deploy when CI should immediately pull and run a deployment operation after the compose update.

Run commands inside a deployment, for tasks such as database migrations after a release:

flatrun deployment actions my-api
flatrun deployment action my-api migrate
flatrun deployment exec my-api -- bin/rails db:migrate
flatrun deployment exec my-api worker -- php artisan queue:restart
flatrun container exec abc123 -- sh -c 'printenv | sort'

deployment action runs a quick action defined on the deployment; deployment actions lists them. deployment exec runs an ad-hoc command instead: the command follows --, and the service is chosen positionally or with --service (a single-service deployment is resolved automatically, a multi-service one must be named). Both run in the service container, honor the deployment's protected-mode rules, and surface the command's output (including on a non-zero exit).

Call any backend endpoint while a polished command is still pending:

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

Check API connectivity:

flatrun health

See docs for guides and command reference.