netrun-pulse-cli 0.1.0

Operator CLI for Netrun Pulse — the swarm-native infrastructure for multi-agent AI development

pulse-cli

Operator CLI for Netrun Pulse — the swarm-native infrastructure for multi-agent AI development.

This is the vibe-coder primary UX from docs/PULSE_NATIVE_WORKFLOW_v1.0.md Sprint B. Wraps the Pulse REST API so you can spin up workstreams, dispatch capabilities, and finalize as PRs without learning the underlying endpoints.

$ pulse new feature/billing --from Netrun-Systems/MyApp
✓ Workstream a3f9c1... created on branch feature/billing
  repo: Netrun-Systems/MyApp
✓ Import complete: 287 files, 4,261,436 bytes in 7.8s

$ pulse dispatch claude-deliverable "Summarize this code" --workstream a3f9c1
[claude-deliverable running...]
✓ claude-deliverable succeeded in 22.7s

  <Claude's response inline...>

$ pulse finalize a3f9c1
✓ Workstream finalized — PR: https://github.com/Netrun-Systems/MyApp/pull/847

Install

From source (today — pre-PyPI)

cd pulse-cli
pip install -e .            # in a virtualenv
# OR
python3 -m pulse_cli.main    # invoke without install

From PyPI (when published)

pip install netrun-pulse-cli

From Homebrew (planned)

brew install netrunsystems/tap/pulse

Auth

The CLI reads a Pulse JWT in this order of precedence:

1. --token <jwt> CLI flag
2. PULSE_TOKEN env var
3. ~/.config/pulse/token file (the convention used by other operator tooling)
4. PULSE_API_KEY env var (workstream-scoped key — for CI / scripts that already have one)

Mint a JWT via the Pulse frontend or /auth/login endpoint; persist to ~/.config/pulse/token for daily use.

Commands

pulse new <branch> [--from <repo>] [--import-mode skip|eager|lazy] [--no-wait]

Create a new workstream. With --from, populates the workstream's hot state from the GitHub repo's current <branch> HEAD. Default import mode is eager — the CLI blocks until import completes (or you can pass --no-wait to return immediately).

Examples:

pulse new main --from Netrun-Systems/Swarm_Native_Code_Management
pulse new feature/x --from owner/repo --no-wait
pulse new scratchpad                                          # empty workstream

pulse list

Show the operator's active workstreams.

pulse capabilities

List all Pulse capability profiles available for dispatch (kamera, vertex-research, claude-agent, claude-deliverable, the 10 personas, etc.).

pulse dispatch <capability> <prompt> [--workstream <id>] [--param k=v ...] [--no-wait] [--timeout <s>]

Dispatch a Pulse capability. Polls until terminal unless --no-wait.

Examples:

pulse dispatch claude-deliverable "Summarize this paragraph"
pulse dispatch kamera "Acme Corp" --param scan_type=deep_dive
pulse dispatch claude-agent "Add stripe webhook" --workstream a3f9c1
pulse dispatch ceo-review "Review the sprint scorecard"

--param accepts KEY=VALUE pairs; values are JSON-parsed when possible (so limit=10 becomes int 10, tags=["a","b"] becomes a list). Repeat --param for multiple values.

pulse finalize <workstream-id>

Squash a workstream and open a GitHub PR via the configured Git Adapter. Requires a workstream with a repo set at init time.

pulse session <workstream-id> [--cli bash|claude|gemini|codex] [--backend docker|e2b|k8s] [--persist] [--auth-profile <name>] [--attach <session_id>]

Take over a Pulse sandbox terminal — kubectl exec-equivalent over a WebSocket bridge. Bridges your local terminal in raw mode to a long-lived sandbox running in Pulse. Exit with Ctrl-D / exit to disconnect; the sandbox stays alive for reattach via --attach <session_id>.

Examples:

# Plain bash inside a workstream
pulse session a3f9c1

# Claude Code in a persistent k8s session (workstation mode)
pulse session a3f9c1 --cli claude --backend k8s --persist

# Reattach to an existing session
pulse session a3f9c1 --attach 2ac22447919c4a18af69edd248ca3b5a

# JSON mode skips the bridge — useful for scripts that just need a session_id
pulse --json session a3f9c1 > session.json

Platform support: Mac and Linux. Windows is not yet supported (needs the msvcrt-based equivalent of termios; v2 follow-up).

Requires the optional [session] install extra:

pip install 'netrun-pulse-cli[session]'

Without this extra, pulse session fails with a clear message pointing at the missing websockets package.

Global flags

• --token <jwt> — explicit JWT (overrides env + file)
• --gateway <url> — gateway URL override (default https://pulse-api.netrunsystems.com; set PULSE_GATEWAY_URL for the same)
• --json — machine-readable JSON output instead of pretty tables. Useful for scripts:

  pulse --json list | jq '.workstreams[].workstream_id'
  

Architecture

pulse_cli/
├── __init__.py    package metadata
├── auth.py        JWT loading + bearer-header construction
├── api.py         thin httpx wrappers around the gateway endpoints
├── main.py        Click subcommands + Rich-formatted output
└── (session.py)   Sprint B.2 — TTY bridge over WebSockets

tests/
├── test_auth.py   credential precedence + header construction
└── test_cli.py    each subcommand against mocked api layer

The CLI is intentionally thin — it doesn't reimplement gateway logic, just composes existing endpoints. New gateway endpoints become CLI subcommands by:

1. Adding a function to api.py (one httpx call)
2. Adding a @cli.command to main.py
3. Adding a behavioral test to tests/test_cli.py

Status

Sprint B.1 + B.2 (current): scaffold + 6 subcommands (new, list, dispatch, finalize, capabilities, session) + 33 unit tests + production smoke tests for create-workstream, dispatch, list-capabilities, and session-creation paths.

Sprint B.3 (planned): PyPI publication, Homebrew formula. Today install via pip install -e . from the repo OR invoke directly via python3 -m pulse_cli.main.

Verification

cd pulse-cli && python3 -m pytest tests/ -v
# 24 passed in 0.3s

Smoke-tested against pulse-api-gateway-00069-64j revision (production):

• pulse capabilities returns 16 entries
• pulse dispatch claude-deliverable "..." --no-wait queues a real job
• pulse new main --from octocat/Hello-World imports the public repo end-to-end (Sprint A regression check)

License

Proprietary — Netrun Systems internal use. See ../docs/IP_PROTECTION_GUIDE_v1.0.md.