@av-pi-studio/cli 0.0.3 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +138 -0
  2. package/package.json +3 -3
package/README.md ADDED
@@ -0,0 +1,138 @@
1
+ # `@av-pi-studio/cli`
2
+
3
+ `pi-studio` — the terminal client for Pi-Studio. Drives a daemon (local or remote) over its
4
+ WebSocket API: run and manage agents, control the local daemon's lifecycle, and drive terminals,
5
+ chat rooms, schedules, loops, worktrees, and permissions from the command line.
6
+
7
+ ---
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ npm install -g @av-pi-studio/cli
13
+ ```
14
+
15
+ This exposes the `pi-studio` binary on your `PATH`. Without a global install, run it via:
16
+
17
+ ```bash
18
+ npx @av-pi-studio/cli [options] [command] [args]
19
+ ```
20
+
21
+ ## Quick start
22
+
23
+ ```bash
24
+ # start a local daemon (if one isn't already running) and print a pairing QR code
25
+ pi-studio daemon start
26
+
27
+ # check daemon health
28
+ pi-studio daemon status
29
+
30
+ # run an agent
31
+ pi-studio agent run --provider pi/claude-3-5-sonnet "implement user authentication"
32
+
33
+ # list agents, attach to stream live output
34
+ pi-studio agent ls
35
+ pi-studio agent attach <agentId>
36
+
37
+ # target a remote daemon instead of the local one
38
+ pi-studio --host workstation.local:6767 agent ls
39
+ ```
40
+
41
+ Run `pi-studio --help` (or `<command> --help`) for the full command tree.
42
+
43
+ ## Global options
44
+
45
+ | Flag | Description |
46
+ |---|---|
47
+ | `-H, --host <host>` | Daemon target — `workstation.local:6767`, `ws://…`, or bare `host:port` |
48
+ | `--password <password>` | Password for a password-protected daemon |
49
+ | `--home <dir>` | Override `$PI_STUDIO_HOME` (used for the client-id store) |
50
+ | `--json` | Render command output as JSON instead of a table |
51
+
52
+ **Connection resolution**: `--host host:port` → `ws://host:port`; `--host ws://…`/`wss://…` is
53
+ used as-is; with no `--host`, the CLI targets `ws://127.0.0.1:6767`.
54
+
55
+ **Default action** (no subcommand):
56
+ - `pi-studio <path>` — open that path as a project on the daemon.
57
+ - `pi-studio` (bare) — ensure a local daemon is running, then print a pairing QR code.
58
+
59
+ ## Command tree
60
+
61
+ ### `agent`
62
+
63
+ | Command | Description |
64
+ |---|---|
65
+ | `agent run --provider pi/<model> "prompt"` | Create an agent and run the first turn |
66
+ | `agent ls` | List all agents |
67
+ | `agent attach <agentId>` | Stream an agent's live events |
68
+ | `agent send <agentId> "prompt"` | Send a follow-up prompt |
69
+ | `agent stop <agentId>` | Interrupt the current turn |
70
+ | `agent wait <agentId>` | Block until the agent goes idle or closes |
71
+ | `agent timeline <agentId>` | Print paged timeline history |
72
+ | `agent inspect <agentId>` | Print the full agent record |
73
+ | `agent archive <agentId>` | Soft-delete |
74
+ | `agent delete <agentId>` | Hard delete |
75
+ | `agent update <agentId>` | Update model/mode/features/title/labels |
76
+ | `agent resume <agentId>` | Resume a closed session |
77
+ | `agent import --provider pi --cwd /path --handle <h>` | Import a provider-native session |
78
+
79
+ Provider spec parsing (`--provider`): `pi/claude-3-5-sonnet` → provider `pi`, model
80
+ `claude-3-5-sonnet`; bare `pi` → provider only; `mock` → the credential-free mock provider.
81
+
82
+ ### `daemon`
83
+
84
+ | Command | Description |
85
+ |---|---|
86
+ | `daemon start` | Spawn a local daemon if one isn't already running, then print a pairing QR |
87
+ | `daemon stop` | Send SIGTERM to the local daemon |
88
+ | `daemon status` | Print health + PID |
89
+ | `daemon set-password <pw>` | Bcrypt-hash a password into `$PI_STUDIO_HOME/config.json` |
90
+ | `daemon pair` | Print the pairing URL/QR for an already-running daemon |
91
+
92
+ ### Feature groups
93
+
94
+ Each of the following maps to the corresponding daemon RPC family:
95
+
96
+ | Group | Sample commands |
97
+ |---|---|
98
+ | `terminal` | `create`, `list`, `close` |
99
+ | `chat` | `create-room`, `post`, `read`, `wait` |
100
+ | `schedule` | `create`, `list`, `delete`, `trigger` |
101
+ | `loop` | `create`, `list`, `stop`, `status` |
102
+ | `provider` | `list`, `models`, `modes`, `refresh` |
103
+ | `worktree` | `create`, `list`, `delete` |
104
+ | `project` | `open`, `list` |
105
+ | `permit` | `respond` — approve/deny a pending tool-call permission request |
106
+
107
+ ## Using it as a library
108
+
109
+ The CLI's building blocks are also exported for programmatic use:
110
+
111
+ ```ts
112
+ import { withDaemon } from "@av-pi-studio/cli";
113
+
114
+ await withDaemon(ctx, opts, async (daemonClient) => {
115
+ // daemonClient is a connected @av-pi-studio/client DaemonClient
116
+ });
117
+ ```
118
+
119
+ `withDaemon` resolves the target URL from `--host`/defaults, connects, runs your callback, then
120
+ disconnects — handling `RpcError`s and connection failures with clean stderr output and non-zero
121
+ exit codes along the way.
122
+
123
+ ## How it talks to the daemon
124
+
125
+ The CLI only ever speaks the WebSocket API via `@av-pi-studio/client` — it never imports from
126
+ `@av-pi-studio/server` directly. A stable per-machine `clientId` is generated on first use and
127
+ stored at `$PI_STUDIO_HOME/client-id`; `clientType` is always `"cli"`.
128
+
129
+ ## Development
130
+
131
+ ```bash
132
+ npm run build # tsc -b (also chmod +x's the published binary)
133
+ npm test -- --project packages/cli
134
+ ```
135
+
136
+ Tests cover command parsing, provider-spec parsing, stream-event formatting, the daemon-control
137
+ state machine, output rendering, and pairing-URL construction — all against an injected
138
+ `CliContext` (stub output sink + mock `DaemonRuntime`), never a real spawned daemon.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@av-pi-studio/cli",
3
- "version": "0.0.3",
3
+ "version": "0.0.4",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -21,8 +21,8 @@
21
21
  "clean": "rm -rf dist *.tsbuildinfo"
22
22
  },
23
23
  "dependencies": {
24
- "@av-pi-studio/client": "^0.0.3",
25
- "@av-pi-studio/protocol": "^0.0.3",
24
+ "@av-pi-studio/client": "^0.0.4",
25
+ "@av-pi-studio/protocol": "^0.0.4",
26
26
  "bcryptjs": "^3.0.3",
27
27
  "commander": "^14.0.3",
28
28
  "qrcode": "^1.5.4"