Docs

Buildfyio CLI

`buildfy` — ship from your terminal.

The Buildfyio CLI is the npm package @fyio/buildfyio-cli. Installing it puts one binary on your PATH, buildfy, and every command on this page, in the dashboard, and in the AI prompts uses that name.

Install

npm i -g @fyio/buildfyio-cli   # binary: buildfy
buildfy login

Deploy

cd my-app
buildfy link                  # link this directory to a project
buildfy deploy                # production deploy of the current branch
buildfy deploy --preview      # preview deploy
buildfy deploy --branch dev   # deploy a specific branch

In a git checkout the platform builds the branch as it is on GitHub. In a directory that is not a git checkout (or with --upload), the CLI packs the directory into a tarball (≤ 100 MB; node_modules, .git, build output and anything listed in .buildfyignore are left out), uploads it, and the build runs from that tree exactly as a clone would. Uploads expire after 24 hours.

buildfy deploy                       # not a git repo → uploads the directory
buildfy deploy --upload --preview    # force an upload from inside a repo
buildfy deploy --prebuilt ghcr.io/acme/app:1.4.2   # deploy an image you already built

--prebuilt skips the build entirely: the deployment pulls the image reference as given, so it must be public or live in the platform registry — the cluster has no credentials for your private registries. The image has to honour the runtime constraints (non-root, read-only root filesystem, PORT).

Deployments: list, roll back, promote, cancel

rollback re-points production at a previous ready deployment's image — no clone, no rebuild, seconds. promote does the same for a ready preview deployment (ship exactly what you tested). cancel stops a queued or running build and frees the builder.

buildfy ls                                   # recent deployments (* = serving production)
buildfy ls --json --limit 50
buildfy rollback                             # pick the previous production release
buildfy rollback dpl_abc123 --yes
buildfy promote dpl_preview42                # preview → production, same image
buildfy cancel                               # newest queued/building deployment
buildfy cancel dpl_abc123

Logs

buildfy logs                                  # latest deployment, build stream
buildfy logs dpl_abc123 --stream deploy        # build | deploy | runtime

Why a build failed

Returns the failure reason, the diagnosis with a suggested fix, and only the error lines. Reach for this before buildfy logs — the raw log runs to thousands of lines and the root cause is rarely in the tail. With --json it is meant to be piped straight into an AI agent.

buildfy errors                                 # newest failed deployment
buildfy errors dpl_abc123                      # a specific one
buildfy errors --json                          # machine-readable, for agents and CI

Environment variables

buildfy env pull --env production --file .env.local
buildfy env pull --no-secrets                  # skip secret-marked values
buildfy env push --env preview --file .env.local
buildfy env push --secret                      # store every new variable as a secret (default: guess by name)
buildfy env set DATABASE_URL=postgres://... --secret

Multi-app projects

A project can hold several apps (the project itself is the primary app). Name the app explicitly: the primary app often shares the project name, and a domain bound to the wrong app serves the wrong site.

buildfy components ls                    # apps and their root dirs
buildfy deploy --app web                 # deploy ONE app; plain deploy releases every app
buildfy project show                     # branch, commands, analytics, server timing
buildfy project set --production-branch main --auto-deploy on

Add, change and remove apps from the terminal. A Dockerfile at <root>/Dockerfile is used automatically when the repo has one (--framework docker says so explicitly); there is no --dockerfile flag because the build does not take another path. Without one, the build detects the runtime. On an API token these three need the admin scope.

buildfy components add api --root apps/api --port 4000 --framework docker --health-path /api/healthz
buildfy components add worker --root apps/worker --kind worker --framework nodejs --start-command "node dist/worker.js"
buildfy components update api --port 8080 --health-path /healthz --min-replicas 1 --max-replicas 3
buildfy components update api --name backend          # rename
buildfy components rm worker --yes                    # deployments stop serving; domains are detached
buildfy deploy --app api                              # ship the new app

Edge settings of the project: --analytics off stops the analytics tracker being injected into HTML responses at the edge (default on); --server-timing on appends a Server-Timing header with edge and origin durations (default off). Both apply within a minute, no redeploy.

buildfy project set --analytics off
buildfy project set --server-timing on
buildfy project show                     # analytics on|off, server timing on|off

Domains

buildfy domains ls
buildfy domains add app.example.com --app web     # asks for the app if you omit --app
buildfy domains verify app.example.com
buildfy domains redirect example.com www.example.com   # 301, same path; --off removes
buildfy domains rm old.example.com

Cron jobs

Schedules are UTC. The runner calls the path on the public URL and sends Authorization: Bearer $CRON_SECRET when that env var is set.

buildfy cron ls
buildfy cron add nightly "0 3 * * *" /api/cron/nightly --method GET
buildfy cron runs nightly                 # time, HTTP status, duration, error
buildfy cron set nightly --schedule "30 3 * * *" --disable
buildfy cron rm nightly

API tokens and CI

Tokens are the same ones as Dashboard → Settings → Tokens. In CI, set BUILDFY_TOKEN and skip buildfy login entirely.

buildfy tokens create --name ci --scopes read,deploy --expires 90d
buildfy tokens create --name agent --scopes read,env:read --org my-team   # one workspace only
buildfy tokens ls
buildfy tokens revoke apt_…

# CI: no login step
BUILDFY_TOKEN=bfy_… buildfy deploy --prod --branch main

Wire up an AI agent

Mints a scoped token for the workspace you pick and registers the hosted MCP server https://mcp.buildfyio.com/mcp in your agent. For Claude Code it runs claude mcp add --scope user --transport http … when the claude binary is on your PATH, otherwise it merges the entry into ~/.claude.json and prints the equivalent command (other servers in that file are left alone). Cursor and Windsurf get the same hosted entry in their own config; Claude Desktop gets the local stdio server, or add the URL under Settings → Connectors with no token at all.

buildfy mcp install claude-code                     # or: cursor | windsurf | claude-desktop
buildfy mcp install claude-code --org my-team       # which workspace the token belongs to (asked if you have several)
buildfy mcp install cursor --scopes read,deploy     # default scopes; add admin for create/update/delete tools
buildfy mcp install claude-code --print-token       # show the token once in full (default: bfy_…last4)

The token is never printed unless you pass --print-token. In CI or any non-interactive shell, pass --org; with several workspaces the command refuses to guess and lists them. A stale ~/.claude/mcp_servers.json entry from older CLI versions (a file Claude Code never read) is removed with a notice. Equivalent manual command:

claude mcp add --scope user --transport http buildfyio https://mcp.buildfyio.com/mcp --header "Authorization: Bearer <token>"

Self-hosted / custom API

Point the CLI at another Buildfyio API with BUILDFY_API_URL (defaults to https://api.buildfyio.com).