Orchestration CLI Reference nfltr-orch
The commands of the orchestration hub and the nodes that run its agents: nfltr orch and nfltr node. They belong to the nfltr-orch binary, which nfltr runs for them. The tunnel, sharing and account commands of nfltr itself are in the client CLI reference.
Installation
curl -fsSL https://nfltr.xyz/install.sh | sh -s -- --with orch installs nfltr and nfltr-orch; nfltr finds nfltr-orch next to itself, then on PATH. nfltr update --apply --with orch adds it to an existing install, and nfltr update --apply keeps every installed binary current.
Orchestration commands (nfltr-orch)
Generated from the nfltr-orch binary, which nfltr runs for these commands (install it with nfltr update --apply --with orch): every public command, its flags as --help prints them, and an example.
nfltr start
Join this machine with a safe default policy and run a first agent task (after nfltr config login)
nfltr start [--max-agents N] [--approval-public-key KEY]Tutorials: Getting started
| Flag | Default | Description |
|---|---|---|
--approval-public-key key | — | the owner's approval key (public half, as another machine's `nfltr start` printed it) for one key across machines; default: the key pair in the nfltr config directory (approval.key), made once |
--max-agents string | 1 | most agent processes this machine's node runs at once (a number, or "cores"); used only when this machine has no node yet |
Example:
nfltr startnfltr orch
Claude hub session for a goal (nfltr orch "<goal>"), plus task, fleet, node, HITL and admin groups
nfltr orch [hub flags] ["<goal>"] OR nfltr orch <group> <command> [flags]Tutorials: Give the hub a goal · Many agents across machines · Use nfltr from Claude Code · Diagnostics
| Command | Description |
|---|---|
nfltr orch task | Inspect or intervene on tasks |
nfltr orch fleet | Fleet health and maintenance |
nfltr orch hitl | List human-intervention queues |
nfltr orch nodes | Machines that launch hub agents on demand |
nfltr orch hub | Zero-setup local hub for Claude Code (MCP on stdio) |
nfltr orch doctor | Check hub prerequisites |
nfltr orch diagnose | Inspect relay and orchestration readiness |
nfltr orch admin | Maintenance commands |
| Flag | Default | Description |
|---|---|---|
--agent-linger duration | — | how long an agent process stays after its task ends (for send_message continuations) |
--agent-relay-access | — | hand the local node's relay credentials to the agents it launches (nested hubs; gives agents your key's full power; operator opt-in; off: model CLIs get no nfltr credential) |
--allow-all-tools | — | launch claude agents with --allow-all-tools |
--allow-cross-session-messaging | — | let claude agents use Claude Code cross-session messaging (operator opt-in; off: agents run isolated) |
--allow-repo glob | — | repository glob (e.g. github.com/org/* or /srv/origins/*, matched on the normalized URL) this hub's local node may work on: a spawn naming a matching repository gets a bare mirror of it and git credentials that answer only for these patterns, and the agent clones it itself; needs --allow-all-tools (repository work needs a shell); repeatable; none = spawns naming a repository go elsewhere |
--claude-cmd string | claude | the claude CLI that runs the hub session |
--e2ee-key-file file | — | pairing key file (at least 32 random bytes, e.g. openssl rand -hex 32) that authenticates end-to-end keys so the relay cannot sit in the middle; every machine needs the same file (env NFLTR_A2A_E2EE_KEY_FILE) |
--hub-agent-model string | — | model for every agent whose spawn names none, applied only on workers whose harness offers it; omitted: the worker's harness decides |
--hub-guidance-file string | — | file of your scheduling guidance for the hub, carried verbatim to the hub model; UTF-8, at most 4 KiB; omitted: nothing is added |
--hub-id string | $NFLTR_HUB_ID, else this project's hub | hub identity (a reattaching hub uses the same id); default: one per project directory, so reopening the project reattaches |
--hub-max-tokens int | — | cap on the tokens (input, output, cache writes; cache reads are not counted) all agents of this hub may report together; 0 = no cap |
--hub-max-usd float | — | cap on the reported cost (USD) of all agents of this hub; needs --hub-max-tokens; 0 = no cap |
--hub-model string | — | model of the hub session itself (claude --model); omitted: claude's own default |
--hub-spawn-policy-file string | — | JSON file of your deny rules for the hub's briefs and messages ({"rules": [{"field": "prompt"|"text", "deny_regex", "reason"}]}): a spawn brief or send_message text a rule matches is refused with its reason; omitted: no rules (none are built in) |
--hub-tools string | — | Claude Code built-in tools the hub session itself may use on this machine, comma-separated exact names (claude --tools, e.g. Read,Grep,Glob; an unknown name, default or a pattern is refused, Bash only when listed); pre-approved, so a goal run never waits on a permission prompt; the hub then acts on this machine while it reads untrusted agent, node and webhook content (operator opt-in; omitted: none, work runs in agents on nodes) |
--inherit-host-claude-config | — | run claude agents, and a hub session nfltr starts (nfltr orch "<goal>"), with this host's user-scope Claude Code setup (settings and hooks, CLAUDE.md, memory, plugins; operator opt-in; off: they run with a clean Claude config, the login from CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY) |
--load-project-settings | — | let claude agents load the task repository's own .claude settings (permission rules, hooks); operator opt-in; off: user-scope settings only |
--max-agents string | — | REQUIRED: most agent processes this machine runs at once (a number, or "cores") |
--proxy-url string | — | relay HTTP base URL (default: NFLTR_PROXY_URL) |
--remote-messages string | — | off (default) or answers: the hub may ask you questions and approvals answered from a device paired with nfltr orch hub pair, end to end encrypted (the relay cannot read them) |
--server string | — | relay gRPC address (default: NFLTR_SERVER, else the zero-setup local relay) |
--workspace string | — | the node's shared directory: an agent turn without a task directory of its own starts there; the node keeps and removes nothing in it for an agent (default: the current directory) |
Example:
nfltr orch "fix the flaky relay test"nfltr orch task
Inspect or intervene on tasks
nfltr orch task <command> [flags]| Command | Description |
|---|---|
nfltr orch task list | List orchestration tasks |
nfltr orch task status | Show task status |
nfltr orch task watch | Watch task events |
nfltr orch task wait | Wait for task terminal state |
nfltr orch task result | Fetch task result |
nfltr orch task diff | Diff task outputs |
nfltr orch task cancel | Cancel tasks |
nfltr orch task cancel-stale | Cancel stale tasks |
nfltr orch task pause | Pause a task |
nfltr orch task unpause | Unpause a paused task |
nfltr orch task steer | Steer an in-flight task |
nfltr orch task approve | Approve a pending item |
nfltr orch task reject | Reject a pending item |
nfltr orch task answer | Answer a worker question |
nfltr orch task events | Replay task event stream |
nfltr orch task audit | Audit task history |
nfltr orch task stats | Task statistics |
nfltr orch task artifact | Task artifacts |
nfltr orch task list
List orchestration tasks
nfltr orch task list [flags]| Flag | Default | Description |
|---|---|---|
--active | — | show only non-terminal tasks (excludes completed, failed, cancelled). Mutually exclusive with --state. |
--actor string | — | filter by optional descriptive actor metadata from assignment.actor |
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--batch string | — | filter by dispatch batch id; shorthand for --filter batch_id=<id> |
--cancelled | — | shortcut for --state cancelled. Mutually exclusive with --state and other shortcut flags. |
--completed | — | shortcut for --state completed only (not the full terminal set). Mutually exclusive with --state and other shortcut flags. |
--failed | — | shortcut for --state failed. Mutually exclusive with --state and other shortcut flags. |
--filter value | — | filter by task metadata field as key=val (repeatable, AND-semantics); e.g. --filter batch_id=iter56-x --filter task_mode=review. Supported keys: batch_id, root_task_id, idempotency_key, task_mode, actor, worker, task_id, state, tags.<key>. Unknown keys match nothing (returns empty, exit 0). |
--format string | wide | display format: wide (default multi-column table) or short (one compact line per task) |
--include-completed | — | alias for --include-terminal: also list completed, failed and cancelled tasks alongside active ones. Mutually exclusive with --active. |
--include-terminal | — | include completed/failed/cancelled tasks in output (default: terminal tasks are hidden). Mutually exclusive with --active. |
--json | — | removed; use --output json |
--limit int | — | limit output to the N most-recently-started tasks after filters (0 = show all) |
--max-age duration | — | only include tasks created within this duration (e.g. --max-age 1h); 0 = no filter; translates to a CreatedAt cutoff of now-duration |
--mine | — | show only tasks owned by the current API-key principal |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--no-recovery-first | — | preserve the requested sort order even when --active, --stalled, or --recovery-priority is set |
--output string | text | output format: text, json, csv, or jsonl |
--peek int | — | limit the table to the N most-recently-updated rows after sort (0 = show all) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--recovery-first | — | sort detached recoveries before other rows; default for --active, --stalled, and --recovery-priority |
--recovery-priority string | — | filter detached recovery priority: normal, high, critical, or comma-separated values |
--reverse | — | reverse sort order so oldest tasks appear first (applies after --sort-by) |
--root string | — | scope the table to one orchestration: matches when the task's own id equals ROOT or when its lineage.root_task_id equals ROOT (i.e. the root task and every descendant) |
--running | — | shortcut for --state running. Mutually exclusive with --state and other shortcut flags. |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--since duration | — | only include tasks updated within this duration (e.g. --since 1h); 0 = no filter |
--sort-by string | age | sort the task list: "age" (newest first), "priority" (high→normal→low), or "state" (lexicographic) |
--stalled | — | show only non-terminal tasks with no event in the last 5 minutes |
--state string | — | filter by task state (e.g. running, accepted, completed) |
--tag value | — | filter by key=value tag (repeatable, AND-semantics); e.g. --tag iter=40 --tag squad=alpha |
--task-mode string | — | filter by task execution mode from assignment.task_mode |
--tasks string | — | comma-separated task ids to narrow the list — useful when supervising a specific parallel set |
--until duration | — | only include tasks updated more than this duration ago (e.g. --until 1h); 0 = no filter; composes with --since for a time window |
--worker string | — | filter by worker agent id |
Example:
nfltr orch task list --activenfltr orch task status
Show task status
nfltr orch task status [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--events int | — | also show the last N timeline events (0 = none); useful for "what just happened" without firing a watch |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--poll-interval duration | 1s | interval between polls when --watch is set |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--result-max-bytes orch result | 4096 | maximum result JSON bytes to print in human output (0 = no limit; use orch result for the full body) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to inspect (required) |
--timeout duration | — | maximum time to wait when --watch is set (0 = no limit); exits 2 on timeout |
--watch | — | poll until terminal state; redraw in-place on TTY, new line on pipe |
Example:
nfltr orch task status --task TASK_IDnfltr orch task watch
Watch task events
nfltr orch task watch [flags]| Flag | Default | Description |
|---|---|---|
--all-tasks | — | stream events for every non-terminal task (broadcast mode; mutually exclusive with --task) |
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--buffer-size int | 1000 | in-memory event ring buffer size; older events are dropped when the consumer is slow (0 = unbounded) |
--filter string | — | regex applied to each serialized event line; only matching lines are emitted |
--json | — | emit raw JSON instead of pretty text |
--list-interval duration | 5s | how often to refresh the active task list when --task is not set |
--max-events int | — | exit after emitting this many events (0 = unbounded). Use for one-shot/scripted checks so the stream doesn't run forever (e.g. piped to head). |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--poll-interval duration | 1s | how often to poll the relay for new events per task |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational events; only emit events whose type starts with task. or worker. |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--since int | — | skip events with sequence <= this value (per task) |
--since-event-id int | — | resume watch: skip events with sequence <= this value (use the last event id seen before disconnect) |
--task string | — | watch only this task id (default: all active tasks) |
--timeout duration | — | exit after this wall-clock duration regardless of activity (0 = no timeout). Guards against a watch pinning a relay connection open indefinitely. |
--types string | — | comma-separated event type filter (e.g. task.dispatched,task.completed) |
--worker string | — | filter by worker agent id (only events for tasks dispatched to this worker) |
Example:
nfltr orch task watch --task TASK_IDnfltr orch task wait
Wait for task terminal state
nfltr orch task wait [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--poll-interval duration | 250ms | how often to re-poll when the batch call returns no terminal event |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to wait on (mutually exclusive with --tasks) |
--tasks string | — | comma-separated task ids; wait fans out across all (mutually exclusive with --task) |
--timeout duration | 30s | max wait duration; exits 2 on timeout |
--types string | — | comma-separated event types to filter on (e.g. task.completed,task.failed) |
Example:
nfltr orch task wait --task TASK_ID --timeout 10mnfltr orch task result
Fetch task result
nfltr orch task result [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--summary-only | — | print just result.summary as a single line; exit 2 if task is non-terminal or has no summary |
--task string | — | task id to print the result of (mutually exclusive with --tasks) |
--tasks string | — | comma-separated task ids; print each result body in order (mutually exclusive with --task) |
Example:
nfltr orch task result --task TASK_IDnfltr orch task diff
Diff task outputs
nfltr orch task diff [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to print the diff of (mutually exclusive with --tasks) |
--tasks string | — | comma-separated task ids; print each in-flight diff in order with a header line (mutually exclusive with --task) |
Example:
nfltr orch task diff --task TASK_IDnfltr orch task cancel
Cancel tasks
nfltr orch task cancel [flags]| Flag | Default | Description |
|---|---|---|
--all-stalled | — | cancel every non-terminal task whose last event is >5m ago; confirms count by default, --yes skips prompt |
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--batch string | — | cancel all non-terminal tasks in this dispatch batch id (mutually exclusive with --task and --tasks) |
--code string | — | cancel all failed tasks whose error.code matches this value (bulk cleanup by error code) |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--reason string | — | operator-supplied cancellation reason recorded on the terminal task event |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to cancel (mutually exclusive with --tasks and --batch) |
--tasks string | — | comma-separated task ids for fan-out cancel (mutually exclusive with --task) |
--yes | — | skip confirmation prompt when used with --all-stalled or --code (for scripts) |
Example:
nfltr orch task cancel --task TASK_ID --reason "superseded"nfltr orch task cancel-stale
Cancel stale tasks
nfltr orch task cancel-stale [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--dry-run | — | print what would be cancelled without actually cancelling |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--older-than string | — | cancel non-terminal tasks whose updated_at is older than this duration (e.g. 10m, 1h) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--reason string | — | operator-supplied cancellation reason recorded on the terminal task event |
--recommended-recovery string | — | only cancel stale tasks whose recommended recovery matches this value (currently: cancel) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
Example:
nfltr orch task cancel-stale --older-than 2h --dry-runnfltr orch task pause
Pause a task
nfltr orch task pause [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--reason string | — | operator-supplied note recorded on the task.paused timeline event (optional) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to pause (required) |
Example:
nfltr orch task pause --task TASK_IDnfltr orch task unpause
Unpause a paused task
nfltr orch task unpause [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to unpause (required) |
Example:
nfltr orch task unpause --task TASK_IDnfltr orch task steer
Steer an in-flight task
nfltr orch task steer [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--message string | — | guidance text injected into the running worker (required) |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--origin string | operator | who sent the steer (operator email, agent id, or 'operator') |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--reason string | — | short why for the audit trail (e.g. 'budget_elapsed 4x; redirect to single-file fix') |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to steer (mutually exclusive with --tasks) |
--tasks string | — | comma-separated task ids for fan-out steering (mutually exclusive with --task) |
Example:
nfltr orch task steer --task TASK_ID --message "run the unit tests first"nfltr orch task approve
Approve a pending item
nfltr orch task approve [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--reason string | — | operator-supplied note recorded with the approval (optional) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to approve (required) |
Example:
nfltr orch task approve --task TASK_IDnfltr orch task reject
Reject a pending item
nfltr orch task reject [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--reason string | — | operator-supplied rejection reason recorded on the failed task (required) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to reject (required) |
Example:
nfltr orch task reject --task TASK_ID --reason "wrong branch"nfltr orch task answer
Answer a worker question
nfltr orch task answer [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--approve | — | approve a setup gate using the SetupApprovalDecision protocol |
--json | — | emit raw JSON instead of pretty text |
--message string | — | answer text to deliver to the worker (required unless --approve or --reject is used) |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--reason string | — | reason recorded with --approve or --reject |
--reject | — | reject a setup gate using the SetupApprovalDecision protocol |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id to answer (required) |
Example:
nfltr orch task answer --task TASK_ID --message "use the staging database"nfltr orch task events
Replay task event stream
nfltr orch task events [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--since int | — | show only events with sequence greater than N |
--tail int | 10 | show last N events (0 = all) |
--task string | — | task id whose event tail to show (required) |
Example:
nfltr orch task events --task TASK_ID --tail 20nfltr orch task audit
Audit task history
nfltr orch task audit [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id whose transition history to dump (required) |
Example:
nfltr orch task audit --task TASK_IDnfltr orch task stats
Task statistics
nfltr orch task stats [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--by string | — | group results by field: worker, priority, or state |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--output string | text | output format: text, json, or csv |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--since duration | — | only include tasks updated within this duration (e.g. 1h, 30m) |
--task-store-file path | — | path of the durable task store a fleet-launched local relay shares and fleet stop reads for its active-task check (not a remote relay's tasks, which orch task commands read); defaults to ${XDG_DATA_HOME:-$HOME/.local/share}/nfltr/tasks.db so fleet setup, launch and stop share it across shells. Pass an explicit path to override, or pass an empty value to opt back into a per-invocation tempfile. |
Example:
nfltr orch task stats --since 24hnfltr orch task artifact
Task artifacts
nfltr orch task artifact <command> [flags]| Command | Description |
|---|---|
nfltr orch task artifact list | List a task's artifacts |
nfltr orch task artifact get | Download an artifact |
nfltr orch task artifact preview | Preview an artifact |
nfltr orch task artifact apply | Check or apply a patch artifact |
nfltr orch task artifact fulfill | Answer an artifact request |
nfltr orch task artifact list
List a task's artifacts
nfltr orch task artifact list [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id whose artifact inventory should be listed (required) |
Example:
nfltr orch task artifact list --task TASK_IDnfltr orch task artifact get
Download an artifact
nfltr orch task artifact get [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--artifact-id string | — | artifact_id to pull (required) |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--output-file string | — | local path to write the artifact bytes to; omit to write to stdout |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id that produced the artifact (required) |
Example:
nfltr orch task artifact get --task TASK_ID --artifact-id ARTIFACT_ID --output-file result.patchnfltr orch task artifact preview
Preview an artifact
nfltr orch task artifact preview [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--artifact-id string | — | artifact_id to preview (required) |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id that produced the artifact (required) |
Example:
nfltr orch task artifact preview --task TASK_ID --artifact-id ARTIFACT_IDnfltr orch task artifact apply
Check or apply a patch artifact
nfltr orch task artifact apply [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--artifact-id string | — | artifact_id to apply as a git patch (required) |
--check | — | validate the patch with git apply --check without mutating the worktree |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id that produced the artifact (required) |
--workdir string | — | git worktree directory where the patch should be checked/applied; default is current directory |
--yes | — | actually apply the patch; required unless --check is set |
Example:
nfltr orch task artifact apply --task TASK_ID --artifact-id ARTIFACT_ID --checknfltr orch task artifact fulfill
Answer an artifact request
nfltr orch task artifact fulfill [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--content string | — | reply text to send with the artifacts |
--content-file string | — | path to reply text, or - for stdin |
--dir value | — | local directory to package as tar.gz; repeat for multiple |
--file value | — | local file to send; repeat for multiple |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task string | — | task id waiting on an artifact request (required) |
Example:
nfltr orch task artifact fulfill --task TASK_ID --file notes.mdnfltr orch fleet
Fleet health and maintenance
nfltr orch fleet <command> [flags]| Command | Description |
|---|---|
nfltr orch fleet status | Fleet status dashboard |
nfltr orch fleet workers | List connected workers |
nfltr orch fleet relay | Manage the host-local relay |
nfltr orch fleet ping | Ping workers |
nfltr orch fleet status
Fleet status dashboard
nfltr orch fleet status [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--label value | — | filter workers by label key=value (repeatable, AND semantics; e.g. --label pool=prod --label flavor=cursor) |
--max-renders int | — | with --watch, stop after N renders (0 = unlimited); useful for tests and bounded snapshots |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--output string | text | output format: text, json, or csv |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--refresh-interval string | 5s | interval between fleet table refreshes when --watch is set |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task-store-file path | — | path of the durable task store a fleet-launched local relay shares and fleet stop reads for its active-task check (not a remote relay's tasks, which orch task commands read); defaults to ${XDG_DATA_HOME:-$HOME/.local/share}/nfltr/tasks.db so fleet setup, launch and stop share it across shells. Pass an explicit path to override, or pass an empty value to opt back into a per-invocation tempfile. |
--timeout duration | — | maximum time to run when --watch is set (0 = no limit); exits 0 when elapsed |
--watch | — | live fleet view: re-render the table on each refresh (in-place on TTY, blank-separated snapshots on pipe) |
Example:
nfltr orch fleet statusnfltr orch fleet workers
List connected workers
nfltr orch fleet workers [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--flavor string | — | filter by flavor (claude-code, copilot, cursor, generic) |
--json | — | emit raw JSON instead of pretty text |
--no-active-tasks | — | skip active-task count enrichment for latency-sensitive inventory lookups |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--output string | text | output format: text or json |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--task-store-file path | — | path of the durable task store a fleet-launched local relay shares and fleet stop reads for its active-task check (not a remote relay's tasks, which orch task commands read); defaults to ${XDG_DATA_HOME:-$HOME/.local/share}/nfltr/tasks.db so fleet setup, launch and stop share it across shells. Pass an explicit path to override, or pass an empty value to opt back into a per-invocation tempfile. |
--with-active-tasks | — | use the relay's live worker inventory (each worker probed) with bounded active-task enrichment. The default relay path performs a bounded active-task digest lookup and renders '?' only when task state is unavailable. |
--worker string | — | filter by worker agent id |
Example:
nfltr orch fleet workers --jsonnfltr orch fleet relay
Manage the host-local relay
nfltr orch fleet relay <command> [flags]| Command | Description |
|---|---|
nfltr orch fleet relay start | Start or attach to the local relay |
nfltr orch fleet relay stop | Stop the local relay |
nfltr orch fleet relay restart | Restart the local relay |
nfltr orch fleet relay status | Show the local relay |
nfltr orch fleet relay start
Start or attach to the local relay
nfltr orch fleet relay start [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | $NFLTR_HOST_LOCAL_API_KEY | API key workers and clients authenticate with (unset: this user's local relay key) |
--docker | — | also let Docker containers on this machine reach the relay at host.docker.internal (for orch fleet setup --mode docker --external-relay): on Linux it also listens on the Docker bridge gateway; Docker Desktop and OrbStack reach loopback already. Without it the relay listens on 127.0.0.1 only |
--grpc-port int | — | worker gRPC port (0 = the relay binds a free port) |
--proxy-port int | — | proxy HTTP port (0 = the relay binds a free port) |
--ready-timeout duration | 1m30s | how long to wait for the relay /ready endpoint |
Example:
nfltr orch fleet relay startnfltr orch fleet relay stop
Stop the local relay
nfltr orch fleet relay stopExample:
nfltr orch fleet relay stopnfltr orch fleet relay restart
Restart the local relay
nfltr orch fleet relay restart [start flags]| Flag | Default | Description |
|---|---|---|
--api-key string | $NFLTR_HOST_LOCAL_API_KEY | API key workers and clients authenticate with (unset: this user's local relay key) |
--docker | — | also let Docker containers on this machine reach the relay at host.docker.internal (for orch fleet setup --mode docker --external-relay): on Linux it also listens on the Docker bridge gateway; Docker Desktop and OrbStack reach loopback already. Without it the relay listens on 127.0.0.1 only |
--grpc-port int | — | worker gRPC port (0 = the relay binds a free port) |
--proxy-port int | — | proxy HTTP port (0 = the relay binds a free port) |
--ready-timeout duration | 1m30s | how long to wait for the relay /ready endpoint |
Example:
nfltr orch fleet relay restartnfltr orch fleet relay status
Show the local relay
nfltr orch fleet relay statusExample:
nfltr orch fleet relay statusnfltr orch fleet ping
Ping workers
nfltr orch fleet ping [--json] [--strict] [--workers ID,ID] [--timeout 10s]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--strict | — | exit 2 when the relay is healthy but no workers are connected |
--timeout duration | 10s | maximum time to wait for the relay to respond (default 10s) |
--workers string | — | comma-separated list of worker agent IDs to check; exits 2 if any are missing |
Example:
nfltr orch fleet ping --jsonnfltr orch hitl
List human-intervention queues
nfltr orch hitl [list] [--worker AGENT_ID] [--kind approval|question] [--limit N] [--json]| Command | Description |
|---|---|
nfltr orch hitl list | List approvals and worker questions |
Example:
nfltr orch hitl list --kind questionnfltr orch hitl list
List approvals and worker questions
nfltr orch hitl [list] [--worker AGENT_ID] [--kind approval|question] [--limit N] [--json]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--kind string | — | filter by HITL kind: approval, question, escalation, review, exception |
--limit int | — | cap the returned queue to N rows (0 = no limit) |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
--worker string | — | filter by worker agent id |
Example:
nfltr orch hitl list --kind questionnfltr orch nodes
Machines that launch hub agents on demand
nfltr orch nodes <command> [flags]| Command | Description |
|---|---|
nfltr orch nodes add | Add a node |
nfltr orch nodes list | List nodes |
nfltr orch nodes stop | Stop this machine's node |
nfltr orch nodes add
Add a node
nfltr orch nodes add <command> [flags]| Command | Description |
|---|---|
nfltr orch nodes add ssh | Add a node over ssh |
nfltr orch nodes add ssh
Add a node over ssh
nfltr orch nodes add ssh [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | $NFLTR_API_KEY | account API key (prefer NFLTR_API_KEY) |
--e2ee | true | encrypt agent-to-agent payloads end to end |
--e2ee-key-file file | — | pairing key file (at least 32 random bytes, e.g. openssl rand -hex 32) that authenticates end-to-end keys so the relay cannot sit in the middle; every machine needs the same file (env NFLTR_A2A_E2EE_KEY_FILE) |
--max-agents string | — | REQUIRED: most agent processes the remote node runs (a number, or "cores") |
--proxy-url url | $NFLTR_PROXY_URL | relay HTTP url (default derived from --server) |
--remote-bin path | — | nfltr-orch (or nfltr with nfltr-orch beside it) path already on the remote; default copies this binary when the remote OS/arch matches |
--server address | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--ssh-command command | ssh | ssh command (with options, e.g. "ssh -p 2222") |
--tls | true | use TLS to the relay |
--wait duration | 1m0s | how long to wait for the node to join the relay |
Example:
nfltr orch nodes add ssh --max-agents 2 user@build-hostnfltr orch nodes list
List nodes
nfltr orch nodes list [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | $NFLTR_API_KEY | account API key (prefer NFLTR_API_KEY) |
--e2ee | true | encrypt agent-to-agent payloads end to end |
--e2ee-key-file file | — | pairing key file (at least 32 random bytes, e.g. openssl rand -hex 32) that authenticates end-to-end keys so the relay cannot sit in the middle; every machine needs the same file (env NFLTR_A2A_E2EE_KEY_FILE) |
--json | — | print node statuses as JSON |
--proxy-url url | $NFLTR_PROXY_URL | relay HTTP url (default derived from --server) |
--server address | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--tls | true | use TLS to the relay |
Example:
nfltr orch nodes listnfltr orch nodes stop
Stop this machine's node
nfltr orch nodes stopExample:
nfltr orch nodes stopnfltr orch hub
Zero-setup local hub for Claude Code (MCP on stdio)
nfltr orch hub [flags] hub for Claude Code on the configured relay, else a zero-setup local one (MCP on stdio)| Command | Description |
|---|---|
nfltr orch hub install-hook | Install the hub's Claude Code hooks |
nfltr orch hub monitors | List the hub's monitors |
nfltr orch hub stop-monitor | Stop a monitor |
nfltr orch hub runs | This machine's hubs and their agents, running or not |
nfltr orch hub show | One agent's turns, result and events |
nfltr orch hub approval-key | Make the owner's approval key pair |
nfltr orch hub approve | Sign one prompt for one node |
nfltr orch hub pair | Pair a phone or browser to answer the hub (end to end encrypted) |
nfltr orch hub devices | List or revoke paired devices |
| Flag | Default | Description |
|---|---|---|
--agent-linger duration | — | how long an agent process stays after its task ends (for send_message continuations) |
--agent-relay-access | — | hand the local node's relay credentials to the agents it launches (nested hubs; gives agents your key's full power; operator opt-in; off: model CLIs get no nfltr credential) |
--allow-all-tools | — | launch claude agents with --allow-all-tools |
--allow-cross-session-messaging | — | let claude agents use Claude Code cross-session messaging (operator opt-in; off: agents run isolated) |
--allow-repo glob | — | repository glob (e.g. github.com/org/* or /srv/origins/*, matched on the normalized URL) this hub's local node may work on: a spawn naming a matching repository gets a bare mirror of it and git credentials that answer only for these patterns, and the agent clones it itself; needs --allow-all-tools (repository work needs a shell); repeatable; none = spawns naming a repository go elsewhere |
--e2ee-key-file file | — | pairing key file (at least 32 random bytes, e.g. openssl rand -hex 32) that authenticates end-to-end keys so the relay cannot sit in the middle; every machine needs the same file (env NFLTR_A2A_E2EE_KEY_FILE) |
--hub-guidance-file string | — | file of your scheduling guidance for the hub, carried verbatim to the hub model; UTF-8, at most 4 KiB; omitted: nothing is added |
--hub-id string | $NFLTR_HUB_ID, else this project's hub | hub identity (a reattaching hub uses the same id); default: one per project directory, so reopening the project reattaches |
--hub-spawn-policy-file string | — | JSON file of your deny rules for the hub's briefs and messages ({"rules": [{"field": "prompt"|"text", "deny_regex", "reason"}]}): a spawn brief or send_message text a rule matches is refused with its reason; omitted: no rules (none are built in) |
--inherit-host-claude-config | — | run claude agents, and a hub session nfltr starts (nfltr orch "<goal>"), with this host's user-scope Claude Code setup (settings and hooks, CLAUDE.md, memory, plugins; operator opt-in; off: they run with a clean Claude config, the login from CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY) |
--load-project-settings | — | let claude agents load the task repository's own .claude settings (permission rules, hooks); operator opt-in; off: user-scope settings only |
--max-agents string | — | REQUIRED: most agent processes this machine runs at once (a number, or "cores") |
--remote-messages string | — | off (default) or answers: the hub may ask you questions and approvals answered from a device paired with nfltr orch hub pair, end to end encrypted (the relay cannot read them) |
--workspace string | — | the node's shared directory: an agent turn without a task directory of its own starts there; the node keeps and removes nothing in it for an agent (default: the current directory) |
Example:
claude mcp add nfltr -- nfltr orch hub --max-agents 2nfltr orch hub install-hook
Install the hub's Claude Code hooks
nfltr orch hub install-hook [flags]| Flag | Default | Description |
|---|---|---|
--file string | .claude/settings.local.json | Claude Code settings file to add the hook to (settings.local.json: this machine only, not committed) |
--hub-id string | — | hub identity the hook waits on; only when the MCP server was added with the same --hub-id (default: the project's hub) |
--prefer-agents | — | also record YOUR preference that code work (edits, builds, tests) runs in agents on your nodes, not in the session itself: a SessionStart hook that tells each session so, attributed to you; --prefer-agents=false removes it (omitted: left as it is) |
--print | — | print the settings JSON instead of writing it |
Example:
nfltr orch hub install-hook --printnfltr orch hub monitors
List the hub's monitors
nfltr orch hub monitors [flags]| Flag | Default | Description |
|---|---|---|
--hub-dir string | — | the hub's state directory (default: beside the task store, as nfltr mcp uses) |
--hub-id string | — | hub identity (default: NFLTR_HUB_ID, else the project's hub, as nfltr mcp uses) |
--json | — | print the monitors as JSON |
--session-end | — | print only running monitors (with how to stop them) and active hooks and schedules, on stderr; exit 2 when any is listed (the SessionEnd hook) |
Example:
nfltr orch hub monitorsnfltr orch hub stop-monitor
Stop a monitor
nfltr orch hub stop-monitor [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | $NFLTR_API_KEY | account API key (prefer NFLTR_API_KEY) |
--e2ee | true | encrypt agent-to-agent payloads end to end |
--e2ee-key-file file | — | pairing key file (at least 32 random bytes, e.g. openssl rand -hex 32) that authenticates end-to-end keys so the relay cannot sit in the middle; every machine needs the same file (env NFLTR_A2A_E2EE_KEY_FILE) |
--hub-dir string | — | the hub's state directory (default: beside the task store, as nfltr mcp uses) |
--hub-id string | — | hub identity (default: NFLTR_HUB_ID, else the project's hub, as nfltr mcp uses) |
--proxy-url url | $NFLTR_PROXY_URL | relay HTTP url (default derived from --server) |
--server address | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--tls | true | use TLS to the relay |
Example:
nfltr orch hub stop-monitor MONITOR_IDnfltr orch hub runs
This machine's hubs and their agents, running or not
nfltr orch hub runs [flags]| Flag | Default | Description |
|---|---|---|
--hub-dir string | — | the hubs' state directory (default: beside the task store, as nfltr mcp uses) |
--hub-id string | — | list only this hub (default: every hub on this machine) |
--json | — | print the hubs and their agents as JSON |
Example:
nfltr orch hub runsnfltr orch hub show
One agent's turns, result and events
nfltr orch hub show [flags]| Flag | Default | Description |
|---|---|---|
--events int | 20 | print the last N events of each turn's task; 0 none, -1 all |
--hub-dir string | — | the hub's state directory (default: beside the task store, as nfltr mcp uses) |
--hub-id string | — | hub identity (default: NFLTR_HUB_ID, else the project's hub, as nfltr mcp uses) |
--json | — | print the agent's turns and events as JSON |
Example:
nfltr orch hub show --hub-id HUB_ID AGENT_IDnfltr orch hub approval-key
Make the owner's approval key pair
nfltr orch hub approval-key [flags]| Flag | Default | Description |
|---|---|---|
--key-label label | owner | with --signer keychain: the keychain label of the key |
--out file | — | file to create with the private key (mode 0600; never overwritten); keep it off the hub's and the nodes' machines. Required unless --signer keychain |
--signer keychain | — | keychain: the key is in the macOS keychain, used only by nfltr-approval-signer (on PATH; make approval-signer) after Touch ID |
Example:
nfltr orch hub approval-key --out ~/.config/nfltr/approval.keynfltr orch hub approve
Sign one prompt for one node
nfltr orch hub approve [flags]| Flag | Default | Description |
|---|---|---|
--expect-digest sha256 | — | the prompt's sha256 the hub's request_approval reported: sign only if the prompt file has exactly that digest, else sign nothing (a copy that differs by a byte is caught here, not by a later denial) |
--key-file file | — | the private key file from approval-key; required unless --signer keychain |
--key-label label | owner | with --signer keychain: the keychain label of the key |
--node id | — | REQUIRED: the node id the agent runs on (list_nodes node_id) |
--prompt-file file | — | REQUIRED: file holding exactly the spawn_agent prompt you approve (- for stdin) |
--signer keychain | — | keychain: the key is in the macOS keychain, used only by nfltr-approval-signer (on PATH; make approval-signer) after Touch ID |
--ttl duration | — | REQUIRED: how long the grant is valid (duration, e.g. 15m) |
Example:
nfltr orch hub approve --key-file ~/.config/nfltr/approval.key --node node-k8s --prompt-file fix.txt --ttl 15mnfltr orch hub pair
Pair a phone or browser to answer the hub (end to end encrypted)
nfltr orch hub pair [flags]| Flag | Default | Description |
|---|---|---|
--dashboard-url string | — | dashboard origin the device pairs from (default: the configured relay's URL) |
--hub-id string | — | hub the pairing page opens (default: $NFLTR_HUB_ID, else this project's hub); pins are per machine, so every hub here accepts the device |
--rotate-identity | — | make a new hub identity key for this machine and forget every paired device (all devices pair again) |
Example:
nfltr orch hub pairnfltr orch hub devices
List or revoke paired devices
nfltr orch hub devices [flags]| Flag | Default | Description |
|---|---|---|
--revoke string | — | device id to unpair |
Example:
nfltr orch hub devices --revoke DEVICE_IDnfltr orch doctor
Check hub prerequisites
nfltr orch doctor [flags]| Flag | Default | Description |
|---|---|---|
--hub-id id | $NFLTR_HUB_ID, else this project's hub | the hub id nfltr orch would use (nodes joined with --serve-hubs serve only the hubs they name) |
--json | — | output the checklist as JSON (for scripting/CI) |
Example:
nfltr orch doctornfltr orch diagnose
Inspect relay and orchestration readiness
nfltr orch diagnose <command> [flags]| Command | Description |
|---|---|
nfltr orch diagnose relay | Probe relay, Cloudflare and origin reachability |
nfltr orch diagnose relay
Probe relay, Cloudflare and origin reachability
nfltr orch diagnose relay [flags]| Flag | Default | Description |
|---|---|---|
--api-key string | — | API key for this orch invocation (overrides $NFLTR_API_KEY and saved config); when empty, env then saved config are used |
--json | — | emit raw JSON instead of pretty text |
--no-derive-proxy | — | disable --proxy-url auto-derivation from --server; keep --proxy-url at its localhost default even when --server points elsewhere (use when the gRPC and HTTP API live at unrelated URLs) |
--origin-url string | — | automation origin HTTP base URL to probe; defaults to $NFLTR_ORCH_INVENTORY_ORIGIN_URL, else api-origin.nfltr.xyz on nfltr.xyz (none with your own relay) |
--proxy-url string | $NFLTR_PROXY_URL, else http://localhost:8080 | NFLTR proxy API base URL |
--quiet | — | suppress informational stderr notices (e.g. proxy-url derivation) |
--server string | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address |
--silent | — | suppress all informational stderr output (fanning-out banner, per-entry 'dispatched task' lines); only errors are emitted. Use for fully scripted pipelines where stderr noise is unacceptable. |
Example:
nfltr orch diagnose relay --jsonnfltr orch admin
Maintenance commands
nfltr orch admin <command> [flags]| Command | Description |
|---|---|
nfltr orch admin cleanup | Remove stale scratch directories and worktrees |
nfltr orch admin task-store | Task store maintenance |
nfltr orch admin cleanup
Remove stale scratch directories and worktrees
nfltr orch admin cleanup --base-dir DIR [--worktrees] [--yes] [--json]| Flag | Default | Description |
|---|---|---|
--base-dir path | — | directory path whose orchestration scratch subtrees should be scrubbed (required) |
--json | — | emit {candidates,deleted,skipped} on stdout |
--worktrees | — | target registered git worktrees beneath --base-dir instead of scratch directories |
--yes | — | actually delete stale scratch dirs instead of dry-running |
Example:
nfltr orch admin cleanup --base-dir ~/src/app --jsonnfltr orch admin task-store
Task store maintenance
nfltr orch admin task-store <command> [flags]| Command | Description |
|---|---|
nfltr orch admin task-store vacuum | Prune terminal tasks |
nfltr orch admin task-store stats | Task store statistics |
nfltr orch admin task-store vacuum
Prune terminal tasks
nfltr orch admin task-store vacuum [flags]| Flag | Default | Description |
|---|---|---|
--before string | 7d | delete terminal tasks whose updated_at is older than now-DURATION (default 7d); accepts Go duration syntax plus 'Nd' and 'Nw' for days/weeks |
--dry-run | — | report what would be deleted without writing the store |
--json | — | emit a single JSON object {deleted, kept, dry_run} on stdout |
--max-events int | — | cap surviving task event history to the newest N events after age pruning; 0 disables the cap |
--max-terminal-tasks int | — | retain at most the newest N terminal tasks after age pruning; active tasks are always kept; 0 disables the cap |
--store string | — | path to the on-disk SQLite task store (legacy JSON is migrated on the first non-dry-run open; default: $XDG_DATA_HOME/nfltr/tasks.db) |
Example:
nfltr orch admin task-store vacuum --before 720h --dry-runnfltr orch admin task-store stats
Task store statistics
nfltr orch admin task-store stats [flags]| Flag | Default | Description |
|---|---|---|
--json | — | emit {"total":N,"file_size_bytes":B,"by_state":{...},"oldest":"...","newest":"..."} on stdout |
--store string | — | path to the on-disk SQLite task store (legacy JSON is migrated on open; default: $XDG_DATA_HOME/nfltr/tasks.db) |
Example:
nfltr orch admin task-store statsnfltr node
Join this machine to the relay; launch hub agents on demand
nfltr node join --max-agents N|cores [flags]Tutorials: Join machines as nodes · End-to-end encryption and pairing keys
| Command | Description |
|---|---|
nfltr node join | Join this machine to the relay as a node that launches hub agents on demand |
Example:
nfltr node join --max-agents 4nfltr node join
Join this machine to the relay as a node that launches hub agents on demand
nfltr node join --max-agents N|cores [flags]| Flag | Default | Description |
|---|---|---|
--agent-claim-timeout duration | 2m0s | exit a launched agent process no task reached within this duration |
--agent-linger duration | — | how long an agent process stays after its task ends so send_message can continue it in the same session; 0 exits it when the task ends |
--agent-pid-namespace | — | run each agent process in its own PID namespace (Linux, util-linux unshare >= 2.38, unprivileged user namespaces): it sees and can signal only its own processes; operator opt-in, advertised as nfltr.agent.pid_namespace=own; the join fails where the platform cannot give one |
--agent-relay-access | — | hand this node's relay credentials (the account API key, the pairing key file) to the agents it launches and their model CLIs, so an agent can run a nested hub ('nfltr mcp --toolset hub'); gives every agent, and anything that prompt-injects it, your key's full power; operator opt-in, advertised as nfltr.agent.relay_access=allowed. Off: the model CLI and its tools get no nfltr credential |
--allow-all-tools | — | launch agents with every tool: claude with --allow-all-tools (skip permission prompts), codex with its danger-full-access sandbox; operator opt-in. Off: claude asks (and is denied) outside its permission mode, codex runs in its workspace-write sandbox |
--allow-cross-session-messaging | — | let launched claude agents use Claude Code cross-session messaging (reach this machine's other Claude sessions); operator opt-in, advertised as nfltr.agent.cross_session_messaging=allowed. Off: agents run isolated and refuse to start if isolation cannot be verified |
--allow-inspect-files | — | let hubs list, find and stat files and map git repositories (tree: tracked paths per directory with counts and sizes; never read contents) under this node's workspace, repository mirrors, task directories and --data-dir entries (inspect_node); operator opt-in, advertised as nfltr.node.inspect_files=allowed. Resources (cores, load, memory, disk, GPUs, agent slots) are always answered |
--allow-monitors | — | let hubs start monitors here (start_monitor): model-free commands run by this machine's shell with this node's user and credentials, each output line delivered to the hub as an event; operator opt-in, advertised as nfltr.node.monitors=allowed |
--allow-repo glob | — | repository glob (e.g. github.com/org/* or /srv/origins/*, matched on the normalized URL) this node's agents may work on: a spawn naming a matching repository gets a bare mirror of it and git credentials that answer only for these patterns, and the agent clones it itself; needs --allow-all-tools (repository work needs a shell); repeatable; none = spawns naming a repository go elsewhere |
--api-key string | $NFLTR_API_KEY | account API key (prefer NFLTR_API_KEY: argv is visible to other users) |
--approval-public-key key | — | the owner's approval key (public half, from `nfltr orch hub approval-key`): a --tool-policy-file rule marked unless_approved is lifted only for a turn carrying the owner's grant for exactly its prompt on this node (`nfltr orch hub approve`); advertised as nfltr.agent.approval=owner_grant; none by default |
--data-dir name=path | — | name=path of a data location on this machine hubs may explore with --allow-inspect-files (inspect_node root name) and agents are told about; repeatable; advertised as nfltr.node.data_dirs |
--e2ee | true | encrypt agent-to-agent payloads end to end (launched agents use the same setting) |
--e2ee-key-file file | — | pairing key file (at least 32 random bytes, e.g. openssl rand -hex 32) that authenticates end-to-end keys so the relay cannot sit in the middle; every machine needs the same file (env NFLTR_A2A_E2EE_KEY_FILE) |
--harness flavor | — | offer only this harness flavor (claude-code or codex; repeatable); default: every harness CLI found on PATH, and spawns then name one with labels.flavor |
--hub-absence-bound duration | 10m0s | an agent process whose finished results no hub acknowledged for this duration (its hub is gone) parks: it frees its --max-agents slot and stays to deliver them when the hub reattaches; 0 = never park |
--idle-hook command | — | maintenance command (this machine's shell, the node's user and environment without its account key, in the workspace) the node runs while none of its agents runs, at most once per --idle-hook-interval, each run bounded by it; an agent launch stops a run first; output in <state>/logs/idle-hook.log, the last run reported as idle_hook in its status; operator opt-in; none by default |
--idle-hook-interval duration | — | with --idle-hook (required with it): at most one run per this duration, counted from each run's start; also each run's time bound |
--inherit-host-claude-config | — | run launched claude agents with this host's user-scope Claude Code setup (user settings and hooks, CLAUDE.md, memory, plugins, MCP servers); operator opt-in, advertised as nfltr.agent.host_claude_config=inherited. Off: agents run with a clean Claude config (credentials from the environment: CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY) and the node refuses to join if it cannot be established |
--keepalive preset | — | how the agent notices a relay gone silent: preset default, fast, nat, datacenter, mobile, or interval=<duration>,timeout=<duration> (default: default, dead within 15s; NFLTR_KEEPALIVE) |
--labels key=value | — | comma-separated key=value labels for this machine; launched agents carry them (nfltr.machine_id=<id> sets the machine id, default the node id) |
--load-project-settings | — | let launched claude agents load the task repository's own Claude Code settings (.claude/settings.json, .claude/settings.local.json: permission rules, hooks); operator opt-in, advertised as nfltr.agent.project_settings=loaded. Off: only user-scope settings load (the clean config, or this host's with --inherit-host-claude-config) |
--log-level level | info | the node's own log level on stderr: debug, info, warn or error |
--machine-description string | — | what this machine gives access to (hosts, VPNs, GPUs, datasets); advertised as nfltr.machine.description |
--machine-resources string | — | comma-separated resource tokens (e.g. gpu.a100,vpn.corp); advertised as nfltr.machine.resources |
--max-agents string | — | REQUIRED: most agent processes this node runs at once: a number, or "cores" for this machine's CPU count |
--name id | node-<host machine id> | node id on the relay, also its machine id (constraints.machine) unless --labels sets nfltr.machine_id |
--proxy-url url | $NFLTR_PROXY_URL | relay HTTP url handed to launched agents (artifact transfer) |
--require-pin | — | launch agents only for spawns hard-pinned to this node's machine (constraints.machine, pin hard), refusing every other spawn as unsatisfiable; the agents it launches take only turns naming this machine; advertised as nfltr.node.require_pin=machine; default: any spawn its machine admits |
--retry-wait seconds | 5 | seconds between connection attempts once an outage passes a minute, doubling on repeated failures (a second at most before that) |
--serve-hubs ids | — | comma-separated hub ids (a hub's --hub-id; a trailing * matches a prefix: team-a-*): launch agents and start monitors only for these hubs, refusing every other hub of the account as unsatisfiable; the agents it launches refuse other hubs' turns too; advertised as nfltr.node.serve_hubs; scopes the account's own hubs, not an authentication boundary; default: any hub |
--server address | $NFLTR_SERVER, else grpc.nfltr.xyz:443 | relay gRPC address (host:port) |
--state-dir string | <nfltr state dir>/nodes/<id> | directory for the node's child registry and agent logs |
--tls | true | use TLS to the relay |
--tool-policy-file file | — | JSON file {"pre_tool_use":[{"tool","input_field","deny_regex","reason"}...]}: tool calls every claude agent here is denied (the same rules and hook as a spawn's tool_policy), written by the operator; malformed fails the join; none by default |
--workspace string | — | the node's shared directory: an agent turn without a task directory of its own starts there; the node keeps and removes nothing in it for an agent (default: the current directory) |
Example:
nfltr node join --max-agents 4