CLI Reference

The FlightDesk CLI connects your local terminal to the FlightDesk dashboard. Its job is keeping task context current — detecting work, capturing branch names, posting status updates, and managing preview environments from the terminal.

Installation

npm install -g @flightdesk/cli

Requires Node.js 18 or later.

Authentication

flightdesk login

Authenticate with your FlightDesk account.

flightdesk login

Opens a browser window to complete OAuth. Credentials are stored in ~/.flightdeskrc. You only need to do this once per machine.

flightdesk logout

Remove stored credentials from this machine.

flightdesk logout

flightdesk whoami

Show the currently authenticated user and organization.

flightdesk whoami

Session Sync

flightdesk watch

Start the background sync daemon. This is the core command — run it whenever you're working with Claude Code.

flightdesk watch

While running, it:

Detects when a Claude Code session becomes active
Associates the session with an open task based on your current directory and project
Captures the branch name as soon as Claude Code creates one
Syncs the branch name back to FlightDesk so PR webhooks can be correlated
Posts timeline events for session start, branch creation, and session end
Updates task status from Dispatched → In Progress → Branch Created automatically

Keep this running in a dedicated terminal tab while you work. It has no noticeable performance impact.

Task Management

flightdesk tasks

List your active tasks.

flightdesk tasks
flightdesk tasks --project my-project
flightdesk tasks --status pr_open

Statuses you can filter on: pending, dispatched, in_progress, branch_created, pr_open, preview_ready, review_running, review_done, qa_approved, merged.

flightdesk task <id>

Show full details for a task including status, branch, PR URL, and preview URL.

flightdesk task abc123

Partial IDs work — you only need enough characters to be unambiguous.

flightdesk create

Create a new task interactively.

flightdesk create

Prompts for project, title, and description. The task is created in Pending status.

flightdesk dispatch <id>

Mark a task as dispatched and copy the generated prompt to your clipboard.

flightdesk dispatch abc123

Paste the prompt into Claude Code to start the session. The watch command picks it up from there.

flightdesk update <id>

Update a task's status or fields.

flightdesk update abc123 --status qa_approved
flightdesk update abc123 --title "New title"

Preview Environments

flightdesk preview <task-id>

Open the preview URL for a task in your browser.

flightdesk preview abc123

flightdesk ssh <task-id>

SSH directly into the preview container for a task.

flightdesk ssh abc123

Requires your public SSH key to be added at Settings → Personal → Security.

flightdesk logs <task-id>

Stream logs from the preview container.

flightdesk logs abc123
flightdesk logs abc123 --lines 200

Configuration

flightdesk config

Show current configuration including API URL, default project, and credential status.

flightdesk config

flightdesk config set <key> <value>

Set a configuration value.

flightdesk config set defaultProject my-project

Environment Variables

These override values in ~/.flightdeskrc:

| Variable | Description | |---|---| | FLIGHTDESK_API_KEY | API key — alternative to flightdesk login for CI or scripting | | FLIGHTDESK_API_URL | Override the API URL (for self-hosted deployments) | | FLIGHTDESK_ORG | Override the active organization slug |

Using in CI

For automated scripts or CI pipelines, use an API key instead of interactive login:

FLIGHTDESK_API_KEY=your-key flightdesk tasks --status pr_open

Generate API keys at Settings → Personal → API Keys.