FlightDeck CLI

FlightDeck CLI is the command line tool that agents and operators use to interact with Wingman workspaces through Tower. It provides local SQLite-backed access to tasks, chat, docs, storage, flows, approvals, and more.

Runtime Support

FlightDeck CLI currently supports Node.js only.

• Use the installed flightdeck-cli binary, npx @runwingman/flightdeck-cli ..., or node src/cli.js ...
• Do not run the CLI with bun

The reason is the local SQLite layer currently uses better-sqlite3, and Bun execution can fail with native addon / ABI mismatches even when the rest of the CLI is otherwise fine.

Quickstart

1. Install

# One-line installer
curl -fsSL https://raw.githubusercontent.com/humansinstitute/wingman-yoke/main/install.sh | bash

# From npm
npm install -g @runwingman/flightdeck-cli

# Or run directly
npx @runwingman/flightdeck-cli --help

For local development:

git clone https://github.com/humansinstitute/wingman-yoke.git
cd wingman-yoke
npm install

Requires Node >= 20. The installer tries npm first and falls back to GitHub until the npm package is published. Set FLIGHTDECK_CLI_INSTALL_METHOD=git to force the GitHub path.

2. Set your identity

export FLIGHTDECK_CLI_NSEC=nsec1...

When FlightDeck CLI runs inside a Wingmen-managed agent session, it can also resolve the per-session bot key automatically from Wingmen using WINGMAN_URL + SESSION_ID, or directly from AGENT_NSEC if that env var is injected into the session.

3. Initialize with a connection token

flightdeck-cli init --token "<connection_token>"

You can also pass the full Agent Connect JSON package — FlightDeck CLI extracts .connection_token automatically.

4. Sync workspace data

flightdeck-cli sync

This pulls workspace records into your local SQLite mirror at ./.flightdeck-cli/flightdeck-cli.db under the folder where you run the CLI.

5. Start working

# Check connection status
flightdeck-cli status

# List and manage tasks
flightdeck-cli tasks list
flightdeck-cli tasks create --title "New task"
flightdeck-cli tasks comment <task-id> --body "Update here"

# Chat
flightdeck-cli chat channels
flightdeck-cli chat send <channel-id> --body "Hello"

# Docs
flightdeck-cli docs list
flightdeck-cli docs create --title "Notes" --content "hello world"

Tip: When running from a local clone, replace flightdeck-cli with node src/cli.js. Do not use bun src/cli.js.

The legacy wingman-yoke binary remains available during the rename window.

State

By default, state lives in:

• ./.flightdeck-cli/flightdeck-cli.db — local SQLite mirror for the current working directory
• ./.flightdeck-cli/config.json — workspace config for the current working directory

Environment variables:

• FLIGHTDECK_CLI_STATE_DIR — override state directory explicitly, including a shared/global path if you want one
• FLIGHTDECK_CLI_NSEC — explicit agent/operator identity override
• AGENT_NSEC — per-agent secret injected by Wingmen sessions
• WINGMAN_URL + SESSION_ID — lets FlightDeck CLI fetch the current session bot key from the running Wingmen server

Compatibility fallbacks (WINGMAN_YOKE_STATE_DIR, WINGMAN_YOKE_NSEC, ./.wingman-yoke, yoke.db, WINGMAN_AP_STATE_DIR, WINGMAN_AUTOPILOT_NSEC, autopilot.db, Bitwarden wm21-nostr) are still supported.

Docker

Build the local image:

docker build -t runwingman/flightdeck-cli .

Run with mounted state:

docker run --rm \
  -e FLIGHTDECK_CLI_NSEC="$FLIGHTDECK_CLI_NSEC" \
  -e FLIGHTDECK_CLI_STATE_DIR=/state \
  -v flightdeck-cli-state:/state \
  runwingman/flightdeck-cli sync

Command Reference

node src/cli.js status
node src/cli.js getLatest

node src/cli.js tasks list
node src/cli.js tasks create --title "New task"
node src/cli.js tasks update <task-id> --state in_progress
node src/cli.js tasks comment <task-id> --body "Looks good"
node src/cli.js tasks reply <comment-id> --body "Following up"
node src/cli.js tasks comment-image <task-id> --file ./image.png --body "See this"
node src/cli.js tasks voice <task-id> --file ./voice.aiff --body "Voice note"

node src/cli.js chat channels
node src/cli.js chat create --title "FlightDeck temp"
node src/cli.js chat messages <channel-id>
node src/cli.js chat context --channel <channel-id> --format json
node src/cli.js chat history --channel <channel-id> --thread <thread-id> --format json
node src/cli.js chat search --query "term" --format json
node src/cli.js chat search --query "find previous budget chats" --deep --reference thread:<thread-id> --format json
node src/cli.js chat related --format json
node src/cli.js chat related --deep --format json
node src/cli.js chat reply-current --body "Reply" --format json
node src/cli.js chat send <channel-id> --body "Hello"
node src/cli.js chat reply <channel-id> --thread <message-id> --body "Reply"
node src/cli.js chat image <channel-id> --file ./image.png --body "Screenshot"
node src/cli.js chat voice <channel-id> --file ./voice.aiff --body "Voice note"

node src/cli.js docs list
node src/cli.js docs create --title "Scratch doc" --content "hello"
node src/cli.js docs show <doc-id>
node src/cli.js docs update <doc-id> --content-file ./doc.md
node src/cli.js directories create --title "Projects"
node src/cli.js directories list
node src/cli.js directories show <directory-id>
node src/cli.js directories update <directory-id> --title "Renamed"
node src/cli.js docs comment <doc-id> --body "Needs work" --line 12
node src/cli.js docs reply <comment-id> --body "Updated"
node src/cli.js docs comment-image <doc-id> --file ./image.png --line 12
node src/cli.js docs voice <doc-id> --file ./voice.aiff --line 12

node src/cli.js scopes create --title "Flight Deck" --level product
node src/cli.js scopes list
node src/cli.js scopes show <scope-id>
node src/cli.js scopes update <scope-id> --title "Flight Deck Core"

node src/cli.js storage upload ./image.png
node src/cli.js audio list
node src/cli.js audio show <audio-note-id>
node src/cli.js audio update-transcript <audio-note-id> --transcript "Transcript text"

Agent Chat Runtime Tools

Phase 03 adds bot-friendly chat runtime commands. These commands persist a local "current chat context" in the SQLite mirror so Wingmen can bootstrap a session once, then use follow-up commands without custom shell glue. Runtime commands only support --format json in Phase 03 and default to JSON even without the global --json flag.

Context resolution order:

• explicit --message
• explicit --thread
• explicit --channel with the most recently active local thread in that channel
• last stored runtime context from local SQLite

chat context --format json

Returns the active channel/thread context with participants and the latest few local thread messages.

{
  "channel_id": "chan_123",
  "thread_id": "msg_root_1",
  "participants": ["npub1bot...", "npub1user..."],
  "recent_messages": [
    {
      "message_id": "msg_root_1",
      "parent_message_id": null,
      "sender_npub": "npub1user...",
      "body": "@wingman can you review this?",
      "attachments": [],
      "updated_at": "2026-04-08T10:00:00.000Z"
    }
  ]
}

chat history --format json

Returns paged local thread history for the active context. The first call returns the latest page in arrival order. Pass the returned cursor back in to page further back.

{
  "channel_id": "chan_123",
  "thread_id": "msg_root_1",
  "messages": [
    {
      "message_id": "msg_reply_2",
      "parent_message_id": "msg_root_1",
      "sender_npub": "npub1bot...",
      "body": "I found the issue in the runtime helper.",
      "attachments": [],
      "updated_at": "2026-04-08T10:03:00.000Z"
    }
  ],
  "cursor": "offset:20"
}

chat search --format json

Phase 05 keeps the Phase 04 workspace-local behavior and adds two bounded enhancements:

• --reference accepts exact message:, thread:, channel:, or mention: hints for direct lookup
• --deep adds bounded thread-level summaries with the top matching message snippets per thread

{
  "query": "find previous budget chats",
  "references": [
    {
      "reference": "thread:msg_root_9",
      "kind": "thread",
      "channel_id": "chan_999",
      "channel_title": "Budget Archive",
      "thread_id": "msg_root_9",
      "root_message_id": "msg_root_9",
      "last_message_id": "msg_reply_11",
      "message_count": 3,
      "updated_at": "2026-04-07T19:12:00.000Z",
      "summary": "Previous discussion about the same rollout.",
      "participants": ["npub1bot...", "npub1user..."]
    }
  ],
  "results": [
    {
      "message_id": "msg_reply_2",
      "channel_id": "chan_123",
      "channel_title": "Agent Chat",
      "thread_id": "msg_root_1",
      "parent_message_id": "msg_root_1",
      "sender_npub": "npub1bot...",
      "body": "I found the issue in the runtime helper.",
      "updated_at": "2026-04-08T10:03:00.000Z",
      "scope": "current_thread"
    }
  ],
  "threads": [
    {
      "channel_id": "chan_123",
      "channel_title": "Agent Chat",
      "thread_id": "msg_root_1",
      "root_message_id": "msg_root_1",
      "last_message_id": "msg_reply_2",
      "message_count": 4,
      "updated_at": "2026-04-08T10:03:00.000Z",
      "summary": "Please review the runtime helper rollout.",
      "participants": ["npub1bot...", "npub1user..."],
      "scope": "current_thread",
      "matching_messages": [
        {
          "message_id": "msg_reply_2",
          "sender_npub": "npub1bot...",
          "body": "I found the issue in the runtime helper.",
          "updated_at": "2026-04-08T10:03:00.000Z"
        }
      ]
    }
  ]
}

chat related --format json

Phase 05 keeps the Phase 04 cross-chat behavior and adds --deep, which includes bounded supporting message snippets from each related thread.

{
  "message_id": "msg_reply_2",
  "related_threads": [
    {
      "channel_id": "chan_123",
      "channel_title": "Agent Chat",
      "thread_id": "msg_root_9",
      "root_message_id": "msg_root_9",
      "last_message_id": "msg_reply_11",
      "message_count": 3,
      "updated_at": "2026-04-07T19:12:00.000Z",
      "summary": "Previous discussion about the same rollout.",
      "participants": ["npub1bot...", "npub1user..."],
      "match_score": 24,
      "relation": {
        "same_channel": false,
        "shared_terms": ["budget", "rollout"],
        "shared_participants": ["npub1bot...", "npub1user..."]
      },
      "matching_messages": [
        {
          "message_id": "msg_reply_11",
          "sender_npub": "npub1user...",
          "body": "Budget notes from the earlier rollout are here.",
          "updated_at": "2026-04-07T19:10:00.000Z"
        }
      ]
    }
  ]
}

chat reply-current --format json

Replies into the active thread root stored in local runtime context, then updates that local context to the newly sent bot message.

{
  "channel_id": "chan_123",
  "thread_id": "msg_root_1",
  "message_id": "msg_bot_reply_3",
  "status": "sent"
}

Development

# Run commands locally
node src/cli.js status
node src/cli.js sync

# Run tests
npm test

Schema compatibility is part of the FlightDeck CLI test suite. It validates supported outbound families against the published Flight Deck manifests in ../sb-publisher/schemas/flightdeck.