@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.
- package/README.md +138 -0
- 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
|
+
"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.
|
|
25
|
-
"@av-pi-studio/protocol": "^0.0.
|
|
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"
|