CLI Reference

The FlightDesk CLI connects your terminal to FlightDesk: filing work, reading where it got to, handing a locally built pull request to the pipeline, and driving preview environments. The same binary is what an orchestrated agent turn uses to report itself, which is why the command list below is longer than you will ever need.

Installation

npm install -g flightdesk

The package is called flightdesk. It installs two binaries — flightdesk and the shorter fd — and requires Node.js 18 or later. Upgrade the same way you installed:

npm install -g flightdesk@latest

Which build am I running?

flightdesk --version
# 0.6.3 (abc1234)

The version is followed by the short commit the bundle was built from, so two builds of one version number can be told apart. A -dirty suffix means it was built from a working tree with uncommitted changes, and unknown means it was built outside a git checkout. flightdesk whoami --json carries the same three facts as cliVersion, cliCommit and cliBuildDate.

Authentication

The CLI authenticates with a personal API token, which you create at Settings → Personal → API Tokens. There is no interactive browser login.

flightdesk init

flightdesk init

Prompts for the token, verifies it against the API, and writes ~/.flightdeskrc with the token and the organizations that token can reach. Run it again to replace the token; it asks before overwriting.

flightdesk whoami

flightdesk whoami
flightdesk whoami --json

Who the resolved token authenticates as, the active organization, and which credential source was used — the fastest way to find out why a command is acting on the wrong account.

Where the credential comes from

Three sources, highest precedence first:

FLIGHTDESK_API_KEY in the environment. With it, FLIGHTDESK_API_URL and FLIGHTDESK_ORGANIZATION_ID are read too.
A .flightdeskrc in the current directory, or in any directory above it up to your home directory. Shape: { "apiKey": "…", "apiUrl": "…", "organizationId": "…" }. The CLI never writes these — they exist so an agent folder on a shared box carries its own identity.
~/.flightdeskrc, written by flightdesk init.

flightdesk whoami prints which one won.

Environment variables

| Variable | Description | |---|---| | FLIGHTDESK_API_KEY | The API token. Overrides every config file — use this in CI. | | FLIGHTDESK_API_URL | Point at another deployment. Same effect as --api. | | FLIGHTDESK_ORGANIZATION_ID | The organization to act in, when the token can see several. |

Global flags

| Flag | Effect | |---|---| | --api <url> | Use this API instead of the configured one | | --dev | Use a local API on localhost:3000 | | --version | Print the version and build commit |

Organizations and repositories

One token covers every organization you belong to. The CLI keeps an active organization and a map from git remote to FlightDesk project, so a command run inside a checkout files against the right project without being told which.

flightdesk org list              # organizations this token can see
flightdesk org switch acme       # change the active one
flightdesk org refresh           # re-read membership after being added to one
flightdesk context               # this checkout's organization and project
flightdesk sync                  # rebuild the repo-to-project map
flightdesk project list          # projects in the active organization

There is no "add organization" command — membership follows the token.

Tasks

flightdesk task create

flightdesk task create -p <project-id> -t "Fix the login redirect loop" \
  -d "Signing in from /settings bounces back to /login"

--project and --title are required. Also accepts --subproject (required when the project has subprojects), --source-system / --source-ref / --source-url to record where the request came from, and --follow-up-of <taskId> to file something real but out of another task's scope — a follow-up lands in Backlog, unassigned, and never dispatches itself.

flightdesk task list

flightdesk task list
flightdesk task list -p <project-id>
flightdesk task list --status PR_OPEN

--status filters on the coding run status — PENDING, DISPATCHED, IN_PROGRESS, BRANCH_CREATED, PR_OPEN, PREVIEW_STARTING, PREVIEW_READY, REVIEW_RUNNING, REVIEW_DONE, QA_READY, QA_CHANGES_REQUESTED, QA_APPROVED, MERGED, ARCHIVED — not on the phase. A task with no coding run shows as "No coding run". See Task Workflow for how the two relate.

flightdesk task status <task-id>

One task in detail: phase, run status, branch, pull request, preview URL and review checks.

flightdesk task update <task-id>

flightdesk task update <task-id> --pr-url https://github.com/acme/app/pull/412
flightdesk task update <task-id> --branch feat/login-redirect
flightdesk task update <task-id> --release-note "Signing in from a deep link now returns to it."

Also --status, --pr-number, --session, and the source-identity flags --source-system / --source-ref / --source-url, with --clear-source to undo a wrong one so pull requests naming it stop binding here.

flightdesk task handoff

flightdesk task handoff --pr 412
flightdesk task handoff --pr https://github.com/acme/app/pull/412 --task <task-id>

Attaches a pull request you built locally and hands the work to the pipeline: it lands where a build turn that pushed lands — waiting on CI — and goes on to QA from there. Without --task it uses, or creates, the task for that pull request. See Agents and Orchestration.

flightdesk task sync <task-id>

Pull the pull request's review state — Copilot feedback, Claude reviews, human reviews — from GitHub now, rather than waiting for the next webhook.

flightdesk register [task-id]

Bind the Claude Code session you are about to start to a task, or create the task in the same call:

flightdesk register <task-id>
flightdesk register --title "Fix the login redirect loop" -p <project-id>

Accepts --view-url and --teleport-id for a cloud session, --description, --prompt, and the same source flags as task create.

flightdesk status

Every active task, in one screen. -p <project-id> narrows it to one project.

flightdesk prompt <task-id>

flightdesk prompt <task-id>                    # review (the default)
flightdesk prompt <task-id> --type test_plan

Prints a prompt built from the task, ready to paste into Claude. review collects the outstanding review feedback; test_plan asks for the steps a human should run on the preview. See Built-in Prompts.

flightdesk comment <task-id>

flightdesk comment <task-id> --body "Waiting on the DNS change before this can be tested."

An internal comment on the task. --ask-agent addresses it to the assigned agent instead, and needs an owner or admin key.

Preview environments

flightdesk preview status <task-id>
flightdesk preview logs <task-id> --lines 200
flightdesk preview logs <task-id> --follow
flightdesk preview restart <task-id>     # re-run the processes, no re-clone
flightdesk preview resume <task-id>      # wake a stopped preview
flightdesk preview teardown <task-id>
flightdesk preview mount <task-id>       # mount the container's filesystem over SSHFS
flightdesk preview unmount <task-id>

mount, unmount and logs also work without the preview prefix — flightdesk logs <task-id> is the same command. --lines is clamped to 1–10000. mount takes -d <path> for a mount directory of your choosing.

See Preview Environments.

Agent commands

These exist for an orchestrated agent turn reporting on itself. They are documented for completeness; a person running the CLI by hand has no reason to use them.

Plans

flightdesk plan submit <task-id> --file plan.md --summary "…" \
  --test-plan test-plan.md --release-note "…"
flightdesk plan show <task-id>
flightdesk plan approve <task-id> --revision 2

A plan is a revision held in FlightDesk, with an optional test plan (the steps a human runs on the preview) and a release note. plan approve is refused for an agent key — approving a plan is a human act.

Questions and decisions

flightdesk questions ask <task-id> --to-role product_owner --key redirect-target \
  --body "Where should a deep link return to after login?" \
  --context "…" --default "The deep link itself"
flightdesk questions list --task <task-id> --status OPEN
flightdesk questions answers <task-id>
flightdesk questions withdraw <question-id>
flightdesk questions decide <task-id> --kind permission \
  --request "Write to apps/web/app/content/docs.ts" \
  --decision "approved: Allow once" --rationale "In scope for this task"

--to-role is one of requester, product_owner, tech_owner, client_contact, triager; --to-user addresses a person directly. An ordinary question carries a proposed --default; --requires-explicit-answer makes it a blocking permission decision with none. questions decide records a native Claude prompt the turn decided itself — audited, and nobody is paged; all four of --kind, --request, --decision and --rationale are required, since a decision with no record of what was asked is not an audit trail. See Pipeline and Gates.

Turns and dispatch

flightdesk turn progress "Reproducing the redirect loop" --dispatch $FLIGHTDESK_DISPATCH_ID
flightdesk turn end --dispatch $FLIGHTDESK_DISPATCH_ID --outcome waiting --waiting-on ci --ref <pr-url>

flightdesk dispatch list
flightdesk dispatch poll
flightdesk dispatch update <id> --status RUNNING
flightdesk dispatch request <task-id> --agent <agent-user-id> --kind EXECUTE
flightdesk agent-bind --path /srv/agents/acme

turn end --outcome is done, waiting, failed or blocked; with waiting, --waiting-on says what for (session, ci, review, qa, merge, deploy, dependency). Note that comment and agent-bind are top-level commands, not subcommands of dispatch.

Using it in CI

Put the token in the environment and the CLI needs no config file at all:

FLIGHTDESK_API_KEY=$FLIGHTDESK_TOKEN flightdesk task list --status PR_OPEN

Create the token at Settings → Personal → API Tokens. It authenticates as you, so scope it as you would your own account — and revoke it on the same page when the pipeline that used it is gone.