CLI Commands

Complete reference for all Starweft CLI commands and flags.

Global Flags

Global flags available for all subcommands.

Flag	Type	Default	Description
`-v, --verbose`	count	`0`	Increase log output (-v: debug, -vv: trace)
`-q, --quiet`	count	`0`	Decrease log output (-q: warn, -qq: error). Mutually exclusive with --verbose

init

Initializes the node's data directory and config.toml.

bash

starweft init --role <ROLE> [OPTIONS]

Flag	Type	Default	Description
`--role`	principal \| owner \| worker \| relay	-	Required. The node's role
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--display-name`	string	`<role>-node`	Display name for the node
`--listen`	multiaddr[]	auto-generated	Listen addresses (multiple can be specified)
`--no-identity`	bool	`false`	Suppress the identity create prompt
`--force`	bool	`false`	Overwrite existing config.toml

Example: Initialize a worker node

bash

starweft init --role worker --data-dir ~/.starweft-worker

run

Starts the node in the foreground and begins inbox polling and message processing.

bash

starweft run [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--role`	principal \| owner \| worker \| relay	config value	Override the role at startup
`--foreground`	bool	`false`	Explicitly run in the foreground
`--log-level`	string	config value	Override the log level (debug, info, warn, error, trace)

Example: Start an owner node

bash

starweft run --data-dir ~/.starweft-owner

identity

Generates and displays Ed25519 key pairs.

identity create

Generates actor_key (and stop_authority_key for principal nodes) and registers the local identity in the store.

bash

starweft identity create [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--principal`	bool	`false`	Generate stop_authority_key even for non-principal roles
`--force`	bool	`false`	Overwrite existing keys

identity show

Displays local identity information.

bash

starweft identity show [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--json`	bool	`false`	Output in JSON format

Example: Check identity

bash

starweft identity show --json

peer

Manages peer node addresses and public keys.

peer add

Registers a peer's multiaddress and adds it to discovery seeds.

bash

starweft peer add <MULTIADDR> [OPTIONS]

Flag	Type	Default	Description
`<MULTIADDR>`	string	-	Required. The peer's multiaddress
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--label`	string	-	Label for the peer (for display purposes)
`--actor-id`	string	auto-generated	The peer's actor ID
`--node-id`	string	auto-generated	The peer's node ID
`--public-key`	string	-	The peer's public key (Base64)
`--public-key-file`	path	-	The peer's public key file. Mutually exclusive with --public-key
`--stop-public-key`	string	-	The peer's stop authority public key (Base64)
`--stop-public-key-file`	path	-	The peer's stop authority public key file
`--capability`	string[]	-	The peer's capabilities (multiple can be specified)

Example: Add an owner peer

bash

starweft peer add /unix/~/.starweft-owner/mailbox.sock \
  --label owner \
  --public-key "BASE64_PUBLIC_KEY"

peer list

Displays a list of registered peers.

bash

starweft peer list [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory

vision

Submits visions (goals) and previews planning results.

vision submit

Sends a vision to the owner and initiates task decomposition. Principal role only.

bash

starweft vision submit --title <TITLE> [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--title`	string	-	Required. Title of the vision
`--text`	string	-	Text body of the vision. Mutually exclusive with --file
`--file`	path	-	File to read the vision text from. Mutually exclusive with --text
`--constraint`	key=value[]	-	Constraints (multiple can be specified: budget_mode, human_intervention, allow_external_agents)
`--owner`	string	auto-resolved	Actor ID of the target owner
`--dry-run`	bool	`false`	Run planning preview only
`--approve`	TOKEN	-	Submit using the approval token obtained from the preview
`--missing-only`	bool	`false`	Used with --dry-run. Display only missing information
`--json`	bool	`false`	Output in JSON format

Example: Preview a vision with dry-run, then submit

bash

# Step 1: Preview
starweft vision submit --title "New feature development" --text "..." --dry-run
 
# Step 2: Submit with the approve token
starweft vision submit --title "New feature development" --text "..." --approve <TOKEN>

vision plan

Displays the planning preview for a vision. Does not submit.

bash

starweft vision plan --title <TITLE> [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--title`	string	-	Required. Title of the vision
`--text`	string	-	Text body of the vision. Mutually exclusive with --file
`--file`	path	-	File to read the vision text from
`--constraint`	key=value[]	-	Constraints (multiple can be specified)
`--owner`	string	-	Actor ID of the target owner
`--missing-only`	bool	`false`	Display only missing information
`--json`	bool	`false`	Output in JSON format

status

Displays the node's health status and statistics.

bash

starweft status [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--json`	bool	`false`	Output in JSON format
`--probe`	liveness \| readiness	-	Run only the specified probe. Mutually exclusive with --watch
`--watch`	bool	`false`	Watch mode with periodic updates
`--interval-sec`	u64	`2`	Update interval in watch mode (seconds)

Example: Run a readiness probe

bash

starweft status --probe readiness

snapshot

Displays a snapshot of a project or task.

bash

starweft snapshot [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project`	string	-	Target project ID
`--task`	string	-	Target task ID
`--request`	bool	`false`	Request a snapshot from a remote node
`--owner`	string	-	Actor ID of the owner to request from
`--watch`	bool	`false`	Watch mode with periodic updates
`--interval-sec`	u64	`2`	Update interval in watch mode (seconds)
`--json`	bool	`false`	Output in JSON format

logs

Displays runtime logs.

bash

starweft logs [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--component`	string	-	Filter by component
`--grep`	string	-	Filter by text pattern
`--since-sec`	u64	-	Display only logs from the last N seconds
`--tail`	usize	`50`	Display the last N lines
`--follow`	bool	`false`	Follow new log output

Example: Follow OpenClaw component logs

bash

starweft logs --component openclaw --follow

events

Displays task events from the event store.

bash

starweft events [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project`	string	-	Filter by project ID
`--task`	string	-	Filter by task ID
`--msg-type`	string	-	Filter by message type
`--tail`	usize	`20`	Display the last N entries
`--follow`	bool	`false`	Follow new events
`--interval-sec`	u64	`2`	Polling interval when following (seconds)

stop

Issues a stop order for a project or task tree. Principal role only.

bash

starweft stop --reason-code <CODE> --reason <TEXT> --yes [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project`	string	-	Project ID to stop. Mutually exclusive with --task-tree
`--task-tree`	string	-	Root ID of the task tree to stop. Mutually exclusive with --project
`--reason-code`	string	-	Required. Stop reason code
`--reason`	string	-	Required. Stop reason text
`--yes`	bool	`false`	Required. Confirm the stop operation
`--json`	bool	`false`	Output in JSON format

Example: Stop a project

bash

starweft stop --project proj_01ABCDEF --reason-code user_requested \
  --reason "Stopping because the goal has been achieved" --yes

wait

Polls until the specified condition is met.

bash

starweft wait [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--vision`	string	-	Target vision ID
`--project`	string	-	Target project ID
`--task`	string	-	Target task ID
`--stop`	string	-	Target stop ID
`--until`	string	-	Wait condition (see below)
`--timeout-sec`	u64	`120`	Timeout (seconds)
`--interval-ms`	u64	`500`	Polling interval (milliseconds)
`--json`	bool	`false`	Output in JSON format

The valid values for --until depend on the scope.

Valid values for --until

--vision: project_created, active, stopped
--project: available, active, approval_applied, stopping, stopped
--stop: ordered, stopping, stopped

project

Lists and approves projects.

project list

Displays a list of projects.

bash

starweft project list [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--status`	string	-	Filter by status
`--approval-state`	string	-	Filter by approval state
`--owner`	string	-	Filter by owner actor ID
`--principal`	string	-	Filter by principal actor ID
`--updated-since`	RFC3339	-	Show only projects updated since the specified date
`--limit`	usize	-	Maximum number of entries to display
`--json`	bool	`false`	Output in JSON format

project approve

Approves a project for execution. Can be run with the owner or principal role.

bash

starweft project approve --project <ID> [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project`	string	-	Required. Project ID to approve
`--owner`	string	-	Owner's actor ID
`--wait`	bool	`false`	Wait until the approval is applied
`--timeout-sec`	u64	`120`	Wait timeout (seconds)
`--interval-ms`	u64	`500`	Polling interval (milliseconds)
`--json`	bool	`false`	Output in JSON format

task

Lists, displays tree views, and approves tasks.

task list

Displays a list of tasks.

bash

starweft task list [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project`	string	-	Filter by project ID
`--status`	string	-	Filter by status
`--approval-state`	string	-	Filter by approval state
`--assignee`	string	-	Filter by assignee actor ID
`--updated-since`	RFC3339	-	Show only tasks updated since the specified date
`--limit`	usize	-	Maximum number of entries to display
`--json`	bool	`false`	Output in JSON format

task tree

Displays the task hierarchy as a tree.

bash

starweft task tree --project <ID> [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project`	string	-	Required. Project ID
`--root`	string	-	Task ID to use as the tree root
`--json`	bool	`false`	Output in JSON format

task approve

Approves a task for execution. Can be run with the owner or principal role.

bash

starweft task approve --task <ID> [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--task`	string	-	Required. Task ID to approve
`--owner`	string	-	Owner's actor ID
`--wait`	bool	`false`	Wait until the approval is applied
`--timeout-sec`	u64	`120`	Wait timeout (seconds)
`--interval-ms`	u64	`500`	Polling interval (milliseconds)
`--json`	bool	`false`	Output in JSON format

export

Exports project and task data in JSON or Markdown format.

export project

bash

starweft export project --project <ID> [OPTIONS]

export task

bash

starweft export task --task <ID> [OPTIONS]

export evaluation

bash

starweft export evaluation --project <ID> [OPTIONS]

export artifacts

bash

starweft export artifacts --project <ID> [OPTIONS]

The following flags are shared across all subcommands.

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project / --task`	string	-	Required. Target project ID or task ID
`--format`	json \| markdown	`json`	Output format
`--output`	path	-	Output file path (defaults to stdout if omitted)

publish

Publishes export data to external services.

publish context

Generates context data for publishing.

bash

starweft publish context [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project`	string	-	Project ID. Mutually exclusive with --task
`--task`	string	-	Task ID. Mutually exclusive with --project
`--format`	json \| markdown	`json`	Output format
`--output`	path	-	Output file path

publish dry-run

Runs a dry run of the publish and generates a preview.

bash

starweft publish dry-run [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project`	string	-	Project ID. Mutually exclusive with --task
`--task`	string	-	Task ID. Mutually exclusive with --project
`--target`	string	`issue`	Target type
`--title`	string	auto-generated	Title for the publish
`--output`	path	-	Output file path

publish github

Posts a comment to a GitHub Issue or Pull Request.

bash

starweft publish github --repo <OWNER/REPO> [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--project`	string	-	Project ID. Mutually exclusive with --task
`--task`	string	-	Task ID. Mutually exclusive with --project
`--repo`	string	-	Required. Repository in owner/repo format
`--issue`	u64	-	Issue number. Mutually exclusive with --pr
`--pr`	u64	-	Pull Request number. Mutually exclusive with --issue
`--title`	string	auto-generated	Title for the comment
`--output`	path	-	Output file path for the result JSON

backup

Backs up and restores all node data.

backup create

Backs up the data directory as a signed bundle.

bash

starweft backup create --output <PATH> [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--output`	path	-	Required. Backup output directory
`--force`	bool	`false`	Overwrite existing output

backup restore

Restores data from a backup bundle.

bash

starweft backup restore --input <PATH> [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the restore destination data directory
`--input`	path	-	Required. Path to the backup bundle
`--force`	bool	`false`	Force restore even if identities do not match

repair

Performs data repair operations.

repair rebuild-projections

Rebuilds projections (project and task snapshots) from the task event log.

bash

starweft repair rebuild-projections [--data-dir <PATH>]

repair resume-outbox

Re-queues outbox messages that are in a pending state.

bash

starweft repair resume-outbox [--data-dir <PATH>]

repair list-dead-letters

Lists undeliverable messages (dead letters).

bash

starweft repair list-dead-letters [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--limit`	usize	`20`	Maximum number of entries to display
`--json`	bool	`false`	Output in JSON format

repair reconcile-running-tasks

Transitions tasks that remain in the running state after a runtime shutdown to a stopped state.

bash

starweft repair reconcile-running-tasks [--data-dir <PATH>]

audit

Verifies the integrity of the event log.

audit verify-log

Verifies the integrity of signatures, hashes, and Lamport timestamps in the task event log.

bash

starweft audit verify-log [--data-dir <PATH>]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory

openclaw

Manages the OpenClaw binary configuration.

openclaw attach

Writes the OpenClaw binary path and settings to config.toml.

bash

starweft openclaw attach --bin <PATH> [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--bin`	string	-	Required. Path or command name of the OpenClaw binary
`--working-dir`	path	-	Working directory for OpenClaw
`--timeout-sec`	u64	-	Task execution timeout (seconds)
`--enable`	bool	`false`	Set openclaw.enabled to true

Example: Attach and enable OpenClaw

bash

starweft openclaw attach --bin /usr/local/bin/openclaw --enable

config

Displays and validates the configuration file.

config show

Displays the current configuration (sensitive information is masked).

bash

starweft config show [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--json`	bool	`false`	Output in JSON format (default is TOML)

config validate

Validates the configuration file for consistency and reports warnings and errors.

bash

starweft config validate [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--json`	bool	`false`	Output in JSON format

registry serve

Starts an HTTP registry server for peer discovery.

bash

starweft registry serve [OPTIONS]

Flag	Type	Default	Description
`--bind`	string	`127.0.0.1:7777`	Bind address
`--ttl-sec`	u64	`300`	TTL for peer entries (seconds)
`--rate-limit-window-sec`	u64	`60`	Rate limit window (seconds)
`--announce-rate-limit`	u64	`300`	Rate limit for the announce endpoint
`--peers-rate-limit`	u64	`900`	Rate limit for the peers endpoint
`--shared-secret`	string	-	Shared secret for HMAC authentication (can also use STARWEFT_REGISTRY_SHARED_SECRET environment variable)
`--shared-secret-env`	string	-	Name of the environment variable containing the shared secret
`--max-body-bytes`	usize	`65536`	Maximum request body size (bytes)
`--read-timeout-ms`	u64	`5000`	Read timeout (ms)
`--write-timeout-ms`	u64	`5000`	Write timeout (ms)
`--allow-insecure-no-auth`	bool	`false`	Allow binding to non-loopback addresses without authentication (not recommended)

metrics

Outputs node metrics in Prometheus text format or JSON.

bash

starweft metrics [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--format`	prometheus \| json	`prometheus`	Output format

dashboard

Displays a real-time TUI dashboard.

bash

starweft dashboard [OPTIONS]

Flag	Type	Default	Description
`--data-dir`	path	`~/.starweft`	Path to the data directory
`--interval-ms`	u64	`1000`	Refresh interval (milliseconds)

completions

Generates shell completion scripts.

bash

starweft completions <SHELL>

Flag	Type	Default	Description
`<SHELL>`	bash \| zsh \| fish \| powershell \| elvish	-	Required. Target shell

Example: Set up zsh completions

bash

starweft completions zsh > ~/.zfunc/_starweft