Metadata-Version: 2.4
Name: netrun-pulse-cli
Version: 0.1.0
Summary: Operator CLI for Netrun Pulse — the swarm-native infrastructure for multi-agent AI development
Author-email: Netrun Systems <daniel@netrunsystems.com>
License: Proprietary
Project-URL: Homepage, https://pulse.netrunsystems.com
Project-URL: Documentation, https://github.com/Netrun-Systems/Swarm_Native_Code_Management/blob/main/pulse-cli/README.md
Project-URL: Source, https://github.com/Netrun-Systems/Swarm_Native_Code_Management/tree/main/pulse-cli
Project-URL: Issues, https://github.com/Netrun-Systems/Swarm_Native_Code_Management/issues
Keywords: pulse,ai,agents,infrastructure,swarm,claude,gemini,codex
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: rich>=13.0.0
Provides-Extra: session
Requires-Dist: websockets>=12.0; extra == "session"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"

# 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)

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

### From PyPI (when published)

```bash
pip install netrun-pulse-cli
```

### From Homebrew (planned)

```bash
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:
```bash
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:
```bash
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:
```bash
# 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:**
```bash
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:
  ```bash
  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

```bash
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`.
