CLI

The SeaWork CLI lets you manage agents from your terminal. It’s the same interface exposed by the daemon’s API, so anything you can do in the app you can do from the command line.

Agent orchestration: You can tell coding agents to use the SeaWork CLI to spawn and manage other agents. This enables multi-agent workflows where one agent delegates subtasks to others and waits for results.

Quick reference

seawork run "fix the tests"           # Start an agent
seawork ls                             # List running agents
seawork attach <id>                    # Stream agent output
seawork send <id> "also fix linting"  # Send follow-up task
seawork logs <id>                      # View agent timeline
seawork stop <id>                      # Stop an agent

Running agents

Use seawork run to start a new agent with a task:

seawork run "implement user authentication"
seawork run --provider codex "refactor the API layer"
seawork run --detach "run the full test suite"  # background
seawork run --worktree feature-x "implement feature X"
seawork run --output-schema schema.json "extract release notes"
seawork run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "summarize release notes"

--worktree flag creates the agent in an isolated git worktree, useful for parallel feature development.

Use --output-schema to return only matching JSON output. You can pass a schema file path or an inline JSON schema object. This mode cannot be used with --detach.

By default, seawork run waits for completion. Use --detach to run in the background.

Listing agents

seawork ls                    # Running agents in current directory
seawork ls -a                 # Include completed/stopped agents
seawork ls -g                 # All directories
seawork ls -a -g --json       # Full list as JSON

Streaming output

Use seawork attach to stream an agent’s output in real-time:

seawork attach abc123   # Attach to agent (Ctrl+C to detach)

Agent IDs can be shortened — abc works if it’s unambiguous.

Sending messages

Send follow-up tasks to a running or idle agent:

seawork send <id> "now run the tests"
seawork send <id> --image screenshot.png "what's wrong here?"
seawork send <id> --no-wait "queue this task"

Viewing logs

seawork logs <id>                  # Full timeline
seawork logs <id> -f               # Follow (streaming)
seawork logs <id> --tail 10        # Last 10 entries
seawork logs <id> --filter tools   # Only tool calls

Waiting for agents

Block until an agent finishes its current task:

seawork wait <id>
seawork wait <id> --timeout 60   # 60 second timeout

Useful in scripts or when one agent needs to wait for another.

Permissions

Agents may request permission for certain actions. Manage these from the CLI:

seawork permit ls                # List pending requests
seawork permit allow <id>        # Allow all pending for agent
seawork permit deny <id> --all   # Deny all pending

Agent modes

Change an agent’s operational mode (provider-specific):

seawork agent mode <id> --list   # Show available modes
seawork agent mode <id> bypass   # Set bypass mode
seawork agent mode <id> plan     # Set plan mode

Daemon management

seawork daemon start             # Start the daemon
seawork daemon status            # Check status
seawork daemon stop              # Stop the daemon

Use SEAWORK_HOME to run multiple isolated daemon instances.

Multi-agent workflows

The CLI is designed to be used by agents themselves. You can instruct an agent to spawn sub-agents for parallel work:

# Agent A spawns Agent B and waits for it
seawork run --detach "implement the API" --name api-agent
seawork wait api-agent
seawork logs api-agent --tail 5

Simple implement + verify loop:

# Requires jq
while true; do
  seawork run --provider codex "make the tests pass" >/dev/null

  verdict=$(seawork run --provider claude --output-schema '{"type":"object","properties":{"criteria_met":{"type":"boolean"}},"required":["criteria_met"],"additionalProperties":false}' "ensure tests all pass")
  if echo "$verdict" | jq -e '.criteria_met == true' >/dev/null; then
    echo "criteria met"
    break
  fi
done

This pattern enables hierarchical task decomposition — a lead agent can break down work, delegate to specialists, and synthesize results.

Output formats

Most commands support multiple output formats for scripting:

seawork ls --json                # JSON output
seawork ls --format yaml         # YAML output
seawork ls -q                    # IDs only (quiet)

Global options

--host <host:port> — connect to a different daemon
--json — JSON output
-q, --quiet — minimal output
--no-color — disable colors