gf CLI

Install the gf command-line tool, sign in, and deploy, manage and script Groundfloor from your terminal.

gf is Groundfloor's command-line tool. Use it to deploy Coderunners, publish Shell apps, and manage secrets, flags and files from your terminal or a CI pipeline.

You need Node.js 20 or later.

npm install -g @groundfloorcloud/cli
gf login          # opens your browser
gf whoami

On a machine without a browser, add --device to sign in with a code instead. Without installing, run any command through npx @groundfloorcloud/cli.

Choose a workspace

gf workspaces                     # list your workspaces
gf workspaces use <workspace-id>  # the default for later commands

Most commands also accept -w <workspace-id> for a single run.

gf workspaces use saves the default for every terminal on your machine, so gf deploy never uses it silently. On a terminal, it shows the saved workspace and asks you to confirm. Without a terminal, such as in CI or when an AI agent runs it, gf deploy refuses until you pass -w <workspace-id> or set GROUNDFLOOR_WORKSPACE_ID.

Commands

Command	What it does
`gf deploy`	Deploy a Coderunner from the current folder or a Git repository. See Functions
`gf coderunner ls`, `status`, `logs`, `run`	List Coderunners, check one, read its logs (`--limit` up to 1000 lines, `--since-seconds` up to 7 days), start a run
`gf coderunner cancel-deployment`	Delete a Coderunner's deployment. See Deleting a deployment
`gf domains add`, `ls`, `verify`, `rm` `--app <id or slug>`	Custom domains for a standalone app. Domains belong to apps, not to Coderunners
`gf apps init`, `create`, `publish`, `ls`	Shell and standalone apps. See Build your first Shell app
`gf secrets ls`, `get`, `set`, `rm`	Secrets. Pass `-` as the value to read it from input
`gf flags ls`, `get`, `set`, `rm`, `compare`, `promote`	Feature flags, with `-e <environment>`
`gf files ls`, `upload`, `download`, `rm`	Files
`gf environments list`	Your workspace's environments
`gf dataplane status`, `provision`	Check or set up the data API for a workspace
`gf usage`	Your organization's plan usage and billing estimate, read-only. `--since-days <n>` sets the billing period (default 30), `--account <id>` picks another organization, `--json` for scripts. See Quotas and limits
`gf token`, `gf env`, `gf m2m token`	Tokens for scripts. See below
`gf api`	Call any API path with your session

gf <command> --help lists every option.

Project settings: `groundfloor.json`

Keep gf deploy settings in a groundfloor.json next to your code, so the command needs no flags. Flags you pass override the file.

groundfloor.json

{
  "name": "greeter",
  "runtime": "node",
  "workloadType": "function",
  "cpu": "250m",
  "memory": "256Mi",
  "env": { "REPORT_REGION": "eu" }
}

Groundfloor doesn't keep deploy-time variable values between deploys, so keeping env here means every gf deploy sends them. gf deploy warns about variables the previous deployment had that this one doesn't send; see Confirmations. Never put secrets in it.

Confirmations

Some commands ask before doing something you might not expect. On a terminal they show what they're about to change and wait for you; without a terminal, they stop unless you pass -y / --yes. The one exception is dropping environment variables, below: without a terminal, gf deploy warns and continues.

Updating an existing Coderunner. If gf deploy finds a Coderunner with the same name, it shows its name, ID and environment and asks before deploying to it.
Dropping environment variables. When gf deploy -c <coderunner> wouldn't send variables the previous deployment had, it lists their names (never their values) and asks "Deploy anyway and clear these variables?". The default is No, which stops before anything is uploaded. --yes skips the question. Without a terminal, such as in CI, it prints the names as a warning and deploys anyway, so send every variable on each deploy. See Deploy them every time.
Deleting a deployment. See below.

--yes doesn't replace choosing a workspace: without a terminal, gf deploy still needs -w or GROUNDFLOOR_WORKSPACE_ID.

Deleting a deployment

gf coderunner cancel-deployment -c <coderunner> (also delete-deployment) deletes the Coderunner's current deployment, or the one you name with --deployment-id. It doesn't stop a deploy in progress: if the deployment is the live one, the Coderunner goes offline until you deploy again. It asks you to confirm on a terminal and needs --yes without one.

Tokens for scripts

Command	Gives you	Use it for
`gf token`	A short-lived token for your own session	Calling the API from your terminal or a local script
`eval "$(gf env)"`	`GROUNDFLOOR_TOKEN`, `CONTROLPLANE_URL` and `GROUNDFLOOR_WORKSPACE_ID` as environment variables	Running your code locally against the workspace's real data
`gf m2m token`	A token for an M2M client, from `GROUNDFLOOR_M2M_CLIENT_ID` and `GROUNDFLOOR_M2M_CLIENT_SECRET`	CI pipelines and servers

eval "$(gf env)"
curl -H "Authorization: Bearer $(gf token)" \
  "$CONTROLPLANE_URL/v1/workspaces/$GROUNDFLOOR_WORKSPACE_ID/vault/collections"

CI pipelines

In CI there's no browser sign-in. Set GROUNDFLOOR_TOKEN to a token and gf uses it instead of a saved session. Set GROUNDFLOOR_WORKSPACE_ID too: without a terminal, gf deploy won't use a saved default workspace.

export GROUNDFLOOR_TOKEN="$(gf m2m token)"   # needs GROUNDFLOOR_M2M_CLIENT_ID and GROUNDFLOOR_M2M_CLIENT_SECRET
export GROUNDFLOOR_WORKSPACE_ID=<workspace-id>
gf coderunner ls

Commands that would ask for confirmation on a terminal need --yes in CI; see Confirmations.

gf deploy waits for the deployment it started. If that deployment fails, is deleted, or isn't ready within 5 minutes, gf deploy exits with a non-zero status and prints the reason, so the pipeline step fails. The previous version keeps serving.

The Developers page in the Client Portal, under Administer, also gives you a short-lived token and a ready-made example request, if you'd rather not use the CLI.

Next steps

AI agents and MCP — let a coding agent work with Groundfloor.
Quick start — deploy your first function.

gf CLI

On this page