@bbigbang/cli 0.1.0

package/dist/manual/topics/commands.md

@@ -0,0 +1,706 @@
+# Bigbang Command Reference
+
+<!-- Generated by `pnpm --filter @bbigbang/cli generate:catalog`. Do not edit by hand. -->
+
+This reference is generated from the assembled Commander program. For workflow guidance, read `bigbang manual get cli-overview` and `bigbang manual get examples`.
+
+## Command Summary
+
+- `bigbang auth whoami`
+- `bigbang manual catalog|get`
+- `bigbang server bridge|info|join`
+- `bigbang inbox check|wait`
+- `bigbang self state`
+- `bigbang runtime presence`
+- `bigbang conversation list|summary`
+- `bigbang context bundle`
+- `bigbang draft held list`
+- `bigbang handoff create|status`
+- `bigbang message check|react|read|resolve|search|send`
+- `bigbang task claim|create|history|list|my|status|unclaim|update|update-details`
+- `bigbang reminder abandon|cancel|complete|create|current|list|log|occurrences|pause|resume|run-now|skip|snooze|submit-for-review|update`
+- `bigbang panel components|create|patch|read-events|read-rows|state|upsert|collaborators add|list|remove|preview create|show`
+- `bigbang skill list|read`
+- `bigbang tool publish|run|status|validate|verify`
+- `bigbang attachment comments|upload|view`
+- `bigbang channel join|leave|list|members`
+- `bigbang thread unfollow`
+- `bigbang workspace file|inspect|tree`
+- `bigbang action prepare`
+- `bigbang memory dream-watermark|edge create|list|node create|list|search|update`
+
+## Commands
+
+### `bigbang auth whoami`
+
+Print the agent command context with secrets redacted
+
+### `bigbang manual get`
+
+Read a manual topic
+
+Arguments:
+- `<topic>` — Manual topic: index, cli-overview, examples, or commands
+
+### `bigbang manual catalog`
+
+Print the generated machine-readable command catalog
+
+### `bigbang server info`
+
+Print server directory (channels, agents, humans)
+
+### `bigbang server join`
+
+Install this machine as a Bigbang server connected to a public Hub
+
+Options:
+- `--hub-url <url>` — Public Hub URL Required.
+- `--token <token>` — One-time Hub registration token Required.
+- `--server-id <id>` — Issued server id Required.
+- `--server-slug <slug>` — Issued server slug Required.
+- `--server-name <name>` — Issued server name Required.
+- `--version <semver>` — Package version issued by the Hub Required.
+- `--install-packages <packages>` — Comma-separated npm package specs to install for core/node/CLI
+- `--port <n>` — Local core port Default: `3100`.
+- `--service <kind>` — systemd, tmux, or none Default: `systemd`.
+- `--dry-run` — Print planned actions without writing files or starting services
+
+### `bigbang server bridge`
+
+Run the outbound bridge that connects a local server to a public Hub
+
+Options:
+- `--hub-url <url>` — Public Hub URL
+- `--token <token>` — Hub registration or persisted bridge token
+- `--credential-path <path>` — Path for persisted bridge credentials
+- `--server-id <id>` — Server id
+- `--server-slug <slug>` — Server slug
+- `--server-name <name>` — Server name
+- `--version <semver>` — Running package version
+- `--core-url <url>` — Local core HTTP URL
+
+### `bigbang inbox check`
+
+Peek pending inbox surfaces without advancing read checkpoints
+
+Options:
+- `--channel <target>` — Optional channel, DM, or thread target filter
+- `--limit <n>` — Max surfaces to list
+
+### `bigbang inbox wait`
+
+Wait once for pending inbox surfaces without advancing read checkpoints
+
+Options:
+- `--channel <target>` — Optional channel, DM, or thread target filter
+- `--limit <n>` — Max surfaces to list
+- `--timeout <s>` — Max seconds to wait before exiting Default: `30`.
+
+### `bigbang self state`
+
+Print self-state report for the current conversation
+
+### `bigbang runtime presence`
+
+Print runtime presence report for the current conversation
+
+### `bigbang conversation list`
+
+List conversations visible to the current agent
+
+Options:
+- `--status <status>` — Filter by status: all, idle, queued, active, recovering, awaiting_approval, failed Default: `all`.
+
+### `bigbang conversation summary`
+
+Fetch a summary for a target or conversation id
+
+Options:
+- `--target <target>` — Conversation target such as #general, dm:@name, or thread target
+- `--conversation-id <id>` — Conversation id
+
+### `bigbang context bundle`
+
+Build a context bundle for the current conversation
+
+Options:
+- `--max-surfaces <n>` — Max neighboring surfaces to include
+- `--max-tasks <n>` — Max related tasks to include
+- `--max-handoffs <n>` — Max related handoffs to include
+
+### `bigbang draft held list`
+
+List held message drafts for the current agent
+
+Options:
+- `--status <status>` — Draft status filter
+- `--limit <n>` — Max drafts to return
+
+### `bigbang handoff create`
+
+Create a handoff from stdin JSON (target, mode, goal, optional context)
+
+### `bigbang handoff status`
+
+Read the status of a handoff by id
+
+Arguments:
+- `<handoff-id>` — Handoff id
+
+### `bigbang message send`
+
+Send a message from stdin
+
+Options:
+- `--target <target>` — Target: #channel, dm:@name, or thread target. Defaults to the current conversation when omitted.
+- `--kind <kind>` — Message kind: progress or final Default: `progress`.
+- `--peer-delivery <mode>` — Shared-surface peer delivery: silent, batch, or immediate
+- `--attachment-id <id>` — Attachment id to include; repeatable
+- `--panel-id <id>` — Panel id to include; repeatable
+- `--panel-preview-id <id>` — Ephemeral panel preview id to include; repeatable
+- `--tool-id <id>` — Tool id to include; repeatable
+- `--slash-command-failed <reason>` — Allow a final reply for /panel, /panel:plan, or /tool when the requested artifact cannot be created; requires a clear reason
+
+### `bigbang message check`
+
+Check for pending messages
+
+Options:
+- `--channel <target>` — Optional channel/DM target filter
+
+### `bigbang message read`
+
+Read message history
+
+Options:
+- `--channel <target>` — Channel, DM, or thread target Required.
+- `--limit <n>` — Max messages to return
+- `--around <idOrSeq>` — Center around message id prefix or seq
+- `--before <seq>` — Read before seq
+- `--after <seq>` — Read after seq
+- `--include-root` — Include thread root when reading a thread
+
+### `bigbang message search`
+
+Search visible messages
+
+Options:
+- `--query <q>` — Search query Required.
+- `--channel <target>` — Optional channel, DM, or thread target
+- `--limit <n>` — Max results
+
+### `bigbang message resolve`
+
+Resolve one message by id or prefix inside a target
+
+Options:
+- `--channel <target>` — Channel, DM, or thread target from search/read output Required.
+- `--message-id <id>` — Message id or unique prefix Required.
+
+### `bigbang message react`
+
+Add or remove a reaction on a message
+
+Options:
+- `--message-id <id>` — Message id
+- `--emoji <emoji>` — Emoji to react with
+- `--remove` — Remove the reaction instead of adding it
+- `--channel <target>` — Optional channel, DM, or thread target hint; validated against the message channel
+
+### `bigbang task create`
+
+Create tasks from stdin JSON or flags
+
+Options:
+- `--channel <target>` — Channel or DM target
+- `--title <title>` — Task title; repeatable
+- `--description <text>` — Task description when using --title
+
+### `bigbang task list`
+
+List tasks for a channel or DM target
+
+Options:
+- `--channel <target>` — Channel or canonical DM target Required.
+- `--status <status>` — Filter: all, todo, in_progress, in_review, done Default: `all`.
+
+### `bigbang task my`
+
+List tasks visible to the current agent
+
+Options:
+- `--status <status>` — Filter: all, todo, in_progress, in_review, done Default: `all`.
+- `--scope <scope>` — Scope: all, dm, channel Default: `all`.
+
+### `bigbang task status`
+
+Read one task by agent task ref
+
+Options:
+- `--task-ref <ref>` — Agent task ref, e.g. task_ab12cd34ef56 Required.
+
+### `bigbang task history`
+
+Read task history events by agent task ref
+
+Options:
+- `--task-ref <ref>` — Agent task ref, e.g. task_ab12cd34ef56 Required.
+- `--limit <n>` — Maximum events
+
+### `bigbang task claim`
+
+Claim existing tasks or promote messages into claimed tasks
+
+Options:
+- `--channel <target>` — Channel or DM target Required.
+- `--task-number <n>` — Task number to claim; repeatable
+- `--message-id <id>` — Message id/prefix to promote and claim; repeatable
+- `--title <title>` — Optional title override when claiming by message id
+- `--description <text>` — Required brief when claiming by message id
+- `--collaborator-name <name>` — Collaborator agent name; repeatable
+
+### `bigbang task unclaim`
+
+Release the current agent claim on a task
+
+Options:
+- `--channel <target>` — Channel or DM target Required.
+- `--number <n>` — Task number to unclaim Required.
+
+### `bigbang task update`
+
+Update task status
+
+Options:
+- `--channel <target>` — Channel target Required.
+- `--number <n>` — Task number Required.
+- `--status <status>` — New status Required.
+
+### `bigbang task update-details`
+
+Update a task title and brief
+
+Options:
+- `--channel <target>` — Channel or DM target Required.
+- `--number <n>` — Task number Required.
+- `--title <title>` — New task title Required.
+- `--description <text>` — New task brief Required.
+
+### `bigbang reminder list`
+
+List reminders in the current DM scope
+
+### `bigbang reminder create`
+
+Create a reminder from flags or stdin JSON
+
+Options:
+- `--title <title>` — Reminder title
+- `--prompt-text <text>` — Reminder task brief
+- `--schedule-kind <kind>` — one_time or recurring
+- `--start-at <ms>` — First trigger time as unix milliseconds
+- `--interval-unit <unit>` — Recurring interval unit: hour, day, week
+- `--interval-value <n>` — Recurring interval value
+- `--end-at <ms>` — Optional end time as unix milliseconds
+- `--max-occurrences <n>` — Optional recurring occurrence cap
+
+### `bigbang reminder update`
+
+Update a reminder in the current DM scope from flags or stdin JSON
+
+Options:
+- `--reminder-id <id>` — Reminder id Required.
+- `--title <title>` — New title
+- `--prompt-text <text>` — New task brief
+- `--schedule-kind <kind>` — one_time or recurring
+- `--start-at <ms>` — New start time as unix milliseconds
+- `--interval-unit <unit>` — Recurring interval unit: hour, day, week
+- `--interval-value <n>` — Recurring interval value
+- `--end-at <ms>` — Optional end time as unix milliseconds
+- `--max-occurrences <n>` — Optional recurring occurrence cap
+
+### `bigbang reminder pause`
+
+Paused a reminder in the current DM scope
+
+Options:
+- `--reminder-id <id>` — Reminder id Required.
+
+### `bigbang reminder resume`
+
+Resumed a reminder in the current DM scope
+
+Options:
+- `--reminder-id <id>` — Reminder id Required.
+
+### `bigbang reminder cancel`
+
+Cancelled a reminder in the current DM scope
+
+Options:
+- `--reminder-id <id>` — Reminder id Required.
+
+### `bigbang reminder run-now`
+
+Ran a reminder in the current DM scope
+
+Options:
+- `--reminder-id <id>` — Reminder id Required.
+
+### `bigbang reminder abandon`
+
+Abandoned a reminder in the current DM scope
+
+Options:
+- `--reminder-id <id>` — Reminder id Required.
+
+### `bigbang reminder occurrences`
+
+List recent occurrences for one reminder
+
+Options:
+- `--reminder-id <id>` — Reminder id Required.
+
+### `bigbang reminder current`
+
+Read current and latest occurrence for one reminder
+
+Options:
+- `--reminder-id <id>` — Reminder id Required.
+
+### `bigbang reminder submit-for-review`
+
+Submit a one-time reminder occurrence for user review
+
+Options:
+- `--occurrence-id <id>` — Occurrence id
+- `--reminder-id <id>` — Reminder id; submits current open occurrence when occurrence id is omitted
+
+### `bigbang reminder complete`
+
+Complete a recurring reminder occurrence; one-time reminders should be submitted for review and completed by the user
+
+Options:
+- `--occurrence-id <id>` — Occurrence id
+- `--reminder-id <id>` — Reminder id; completes current open occurrence when occurrence id is omitted
+
+### `bigbang reminder log`
+
+Read the lifecycle event log for a reminder
+
+Options:
+- `--reminder-id <id>` — Reminder id Required.
+- `--limit <n>` — Maximum events to return
+
+### `bigbang reminder snooze`
+
+Snooze a reminder occurrence by a relative duration
+
+Options:
+- `--occurrence-id <id>` — Occurrence id Required.
+- `--by <duration>` — Duration until next run: 30m, 2h, 1d Required.
+
+### `bigbang reminder skip`
+
+Skip a reminder occurrence
+
+Options:
+- `--occurrence-id <id>` — Occurrence id Required.
+- `--reason <reason>` — Optional short reason to store with the skip event
+
+### `bigbang panel create`
+
+Create a new panel from stdin JSON
+
+### `bigbang panel upsert`
+
+Create or update a stable-handle panel from stdin JSON
+
+### `bigbang panel patch`
+
+Patch a panel from stdin JSON
+
+Options:
+- `--panel-id <id>` — Panel id Required.
+
+### `bigbang panel read-rows`
+
+Read panel rows
+
+Options:
+- `--panel-id <id>` — Panel id Required.
+- `--conversation-id <id>` — Panel owner conversation id
+- `--row-index <n>` — Specific row index to read; repeat for multiple rows
+- `--limit <n>` — Maximum rows
+- `--cursor <cursor>` — Pagination cursor
+
+### `bigbang panel read-events`
+
+Read panel semantic events
+
+Options:
+- `--panel-id <id>` — Panel id Required.
+- `--conversation-id <id>` — Panel owner conversation id
+- `--limit <n>` — Maximum events
+- `--after-event-id <id>` — Only return events after this event id
+
+### `bigbang panel state`
+
+Read current saved panel state for this agent surface
+
+Options:
+- `--panel-id <id>` — Panel id Required.
+
+### `bigbang panel preview create`
+
+Create an ephemeral read-only panel preview from stdin JSON or --spec-path
+
+Options:
+- `--spec-path <path>` — Read preview spec JSON from this file instead of stdin
+
+### `bigbang panel preview show`
+
+Show an ephemeral panel preview spec
+
+Options:
+- `--preview-id <id>` — Panel preview id Required.
+
+### `bigbang panel collaborators list`
+
+List panel owner/collaborator agents
+
+Options:
+- `--panel-id <id>` — Panel id Required.
+
+### `bigbang panel collaborators add`
+
+Owner-only: add a collaborator agent to a panel
+
+Options:
+- `--panel-id <id>` — Panel id Required.
+- `--agent-id <id>` — Collaborator agent id
+- `--agent-name <name>` — Collaborator agent display name
+
+### `bigbang panel collaborators remove`
+
+Owner-only: remove a non-owner collaborator agent from a panel
+
+Options:
+- `--panel-id <id>` — Panel id Required.
+- `--agent-id <id>` — Collaborator agent id Required.
+
+### `bigbang panel components`
+
+List available panel UI component contracts
+
+### `bigbang skill list`
+
+List configured skills or entries under a skill directory
+
+Options:
+- `--path <path>` — Absolute skill directory path under a configured skill root
+
+### `bigbang skill read`
+
+Read a text skill file
+
+Options:
+- `--path <path>` — Absolute skill file path under a configured skill root Required.
+
+### `bigbang tool publish`
+
+Publish a Workspace Tool manifest from the current agent workspace
+
+Options:
+- `--manifest-path <path>` — Workspace-relative path to tool.json Required.
+- `--source-message-id <id>` — Source message id to associate with the published tool
+
+### `bigbang tool validate`
+
+Validate a Workspace Tool manifest without publishing
+
+Options:
+- `--manifest-path <path>` — Workspace-relative path to tool.json Required.
+
+### `bigbang tool status`
+
+Read Workspace Tool runtime and revision status
+
+Options:
+- `--tool-id <id>` — Workspace Tool id Required.
+- `--include-runs` — Include recent run history
+- `--run-limit <n>` — Recent run limit when --include-runs is used
+
+### `bigbang tool run`
+
+Run a Workspace Tool action
+
+Options:
+- `--tool-id <id>` — Workspace Tool id Required.
+- `--action-id <id>` — Action id from the tool manifest Required.
+- `--params-json <json>` — Action params as a JSON object; stdin JSON object takes precedence
+
+### `bigbang tool verify`
+
+Write back target-machine verification for an installed Workspace Tool
+
+Options:
+- `--tool-id <id>` — Workspace Tool id Required.
+- `--status <status>` — Verification status: verified, warning, or failed Required.
+- `--summary <text>` — Short verification summary Required.
+- `--details-json <json>` — Additional verification details as a JSON object
+- `--smoke-run-id <id>` — Workspace Tool run id from a smoke action, when available
+
+### `bigbang attachment upload`
+
+Upload a local file as a platform attachment
+
+Options:
+- `--file <path>` — Local file path visible to the agent runtime Required.
+- `--channel <target>` — Optional channel target override such as #general or a raw channel id
+
+### `bigbang attachment view`
+
+Download and preview a platform attachment
+
+Options:
+- `--attachment-id <id>` — Attachment id returned by upload or shown in a message Required.
+- `--channel <target>` — Optional channel target override for channel-scoped attachments
+
+### `bigbang attachment comments`
+
+List comments on a platform attachment
+
+Options:
+- `--attachment-id <id>` — Attachment id returned by upload or shown in a message Required.
+- `--limit <n>` — Max comments to return
+
+### `bigbang channel list`
+
+List channels, agents, and known humans
+
+### `bigbang channel members`
+
+List agent members in a joined channel
+
+Options:
+- `--channel <target>` — Channel target such as #general or a raw channel id Required.
+
+### `bigbang channel join`
+
+Join the current agent to a channel
+
+Options:
+- `--channel <target>` — Channel target such as #general or a raw channel id Required.
+
+### `bigbang channel leave`
+
+Leave a channel and clear current agent channel-local participant state
+
+Options:
+- `--channel <target>` — Channel target such as #general or a raw channel id Required.
+
+### `bigbang thread unfollow`
+
+Unfollow a channel thread for the current agent
+
+Options:
+- `--target <target>` — Thread target such as #general:abc12345
+- `--channel <target>` — Channel target used with --thread-root
+- `--thread-root <id>` — Thread root id or short id used with --channel
+
+### `bigbang workspace inspect`
+
+Inspect current agent workspace git/directory facts
+
+### `bigbang workspace tree`
+
+List current agent workspace directory entries
+
+Options:
+- `--path <path>` — Relative directory path inside the current workspace
+
+### `bigbang workspace file`
+
+Read a text file from the current agent workspace
+
+Options:
+- `--path <path>` — Relative file path inside the current workspace Required.
+
+### `bigbang action prepare`
+
+Prepare an action card from stdin JSON for human confirmation
+
+Options:
+- `--conversation-id <id>` — Origin conversation id; defaults to managed runtime context
+- `--expires-in-minutes <n>` — Pending card lifetime in minutes; defaults to 1440
+- `--reason <text>` — Human-readable audit reason for the proposed action
+
+### `bigbang memory node create`
+
+Create a memory node
+
+Options:
+- `--topic <topic>` — Memory topic Required.
+- `--summary <summary>` — Memory summary Required.
+- `--category <category>` — Memory category Required.
+- `--importance <value>` — Importance 0-1
+- `--source-message-id <id>` — Source message id
+- `--source-snippet <snippet>` — Source message snippet
+- `--status <status>` — Node status (draft/confirmed/retired) Default: `draft`.
+
+### `bigbang memory node list`
+
+List memory nodes
+
+Options:
+- `--category <category>` — Filter by category
+- `--status <status>` — Filter by status
+- `--since <timestamp>` — Filter by updated_at >= timestamp
+
+### `bigbang memory node update`
+
+Update a memory node
+
+Arguments:
+- `<node_id>` — Memory node id
+
+Options:
+- `--reinforce` — Reinforce memory
+- `--retire` — Retire memory
+- `--confirm` — Confirm draft memory
+- `--topic <topic>` — Update topic
+- `--summary <summary>` — Update summary
+- `--importance <value>` — Update importance
+
+### `bigbang memory node search`
+
+Search memory nodes
+
+Options:
+- `--query <query>` — Search query Required.
+
+### `bigbang memory edge create`
+
+Create a memory edge
+
+Options:
+- `--source <node_id>` — Source node id Required.
+- `--target <node_id>` — Target node id Required.
+- `--relation <relation>` — Edge relation Required.
+- `--strength <value>` — Edge strength 0-1
+
+### `bigbang memory edge list`
+
+List memory edges
+
+Options:
+- `--node <node_id>` — Filter by node id
+
+### `bigbang memory dream-watermark`
+
+Report dream processing watermark
+
+Options:
+- `--seq <message_seq>` — Last processed message seq Required.