CLI

The Fleeet CLI is a zero-dependency Node script that posts events to your board.

Installation

The CLI ships with the kit:

git clone https://github.com/nan-labs/fleeet.git
cd fleeet

No npm install needed. It uses only Node built-ins.

Setup

Set your token:

export FLEEET_TOKEN=<your-token>

Optional environment variables:

export FLEEET_ENDPOINT=https://fleeet.space  # default
export FLEEET_AGENT=my-agent                 # defaults to $USER
export FLEEET_SURFACE="Claude Code"          # optional, max 32 chars

Usage

Start

node bin/fleeet-emit.mjs session_start \
  --task "fix the nav bug" \
  --summary "starting work on nav z-index"

Prints the run_id and stores it in /tmp/fleeet-run-id.

Heartbeat

node bin/fleeet-emit.mjs heartbeat \
  --summary "nav fix done, testing" \
  --progress.commits 1

Blocked

node bin/fleeet-emit.mjs blocked \
  --summary "stuck on color choice" \
  --blocker.kind design_call \
  --blocker.question "blue or green?"

End

node bin/fleeet-emit.mjs session_end \
  --summary "nav bug fixed" \
  --outcome.status shipped \
  --outcome.artefacts '[{"kind":"pr","url":"https://...","label":"PR #123"}]'

Flags

Common flags:

--task: Task description (session_start only)
--summary: One sentence, present tense, no period
--trigger: user, routine, or agent (default: user)
--source.repo: e.g. owner/repo
--project: Claude/ChatGPT Project name, or repo/workspace folder name
--surface: Surface label (overrides FLEEET_SURFACE)
--progress.commits N
--blocker.kind: ambiguity, missing_credential, failing_dep, design_call, access, other
--blocker.question
--outcome.status: shipped, abandoned, handed_off, failed
--outcome.artefacts: JSON array
--outcome.usage: Token counts if your tool reports them, e.g. '{"input_tokens":182000,"output_tokens":9400,"source":"reported"}'

Use dot notation for nested fields: --source.repo owner/repo.

Version

fleeet-emit --version prints the kit version. Every event carries it as client.skill_version. When fleeet.space reports a newer version, the CLI prints a one-line notice on stderr (at most once a day) with a link to Updating the skill. It never updates itself, and it ignores update info from any endpoint other than fleeet.space.

Run ID

The CLI generates run_id on session_start and stores it in /tmp/fleeet-run-id. Subsequent events read it from there.

Override with:

export FLEEET_RUN_ID=<uuid>

Local spool

If the POST fails (network error, server down), events land in ./.fleeet/events.jsonl instead. The CLI doesn’t retry; you can replay them manually or leave them as a local log.

Help

node bin/fleeet-emit.mjs --help

CLI