zeroski 0.0.1

zero.ski CLI — @-protocol dispatch, streaming chat, and trace feed for the Zero runtime
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

# zeroski

The official CLI for **[zero.ski](https://zero.ski)** — the Zero runtime.

`zeroski` speaks the Zero runtime's public HTTP contract: stream chat, dispatch
the `@`-protocol, read your agent identity, and tail traces. It's a thin,
correct Rust client — no hidden magic, one `reqwest` client per invocation, and
the full wire format visible on your terminal.

```
$ zeroski chat "say hello in one word"
Hello.
[deepseek-chat] in=6 out=1 cost=$0.000012

$ zeroski me
{
  "agent_id": "06bfd230…",
  "pubkey": "…",
  "scopes": ["public"]
}

$ zeroski at help
{ "success": true, "result": { "commands": ["help", "search", "recap", …] } }
```

## Install

Rust users:

```bash
cargo install zeroski
```

Pre-built binaries and Homebrew taps ship with the next release.

## Usage

```
zeroski <command> [options]

Commands:
  chat [text…]            Stream /api/chat. Reads stdin when text is omitted.
                          Flags: --model <name>
  at   <cmd> [text…]      POST /@ with { cmd, args }.
                          Flags: --json '<raw-json>'  (use as args verbatim)
  me                      GET /api/me.
  traces [--agent <hex>] [--limit N]
                          GET /traces/agent/:id. Auto-discovers agent via /api/me.
  config                  Print the effective configuration (key masked).

Global flags:
  --base <url>            Override API base (default: https://zero.ski)
  --key  <token>          Override API key
```

## Configuration

Precedence: **CLI flag > environment > config file > defaults**.

| Setting | CLI flag | Env var         | Config file key |
|--------:|----------|-----------------|-----------------|
| Base    | `--base` | `ZEROSKI_BASE`  | `base`          |
| API key | `--key`  | `ZEROSKI_KEY`   | `key`           |

Config file (TOML):

- Linux:   `~/.config/zeroski/config.toml`
- macOS:   `~/Library/Application Support/ski.zero.zeroski/config.toml`
- Windows: `%APPDATA%\zero\zeroski\config\config.toml`

Example:

```toml
base = "https://zero.ski"
key  = "zsk_live_…"
```

`zeroski config` prints the resolved values (key masked: first 4 chars + length).

## Streaming format

`zeroski chat` consumes the server's SSE frames (OpenAI-compat delta shape) and
prints each `content` delta to stdout without extra newlines — it types like a
tty. A one-line `[model] in=… out=… cost=$…` summary goes to stderr once the
`done` frame arrives. Pipe-friendly: redirect stdout for just the answer,
redirect stderr for just the telemetry.

## `@`-protocol

```bash
zeroski at help
zeroski at search "oil filter Toyota 4Runner 2005"
zeroski at recap --json '{"from":"2026-04-01","to":"2026-04-18"}'
```

`zeroski at` wraps the structured shape (`{"cmd": "...", "args": {...}}`). Free-form
trailing text becomes `args.text`; `--json` sets `args` verbatim.

## Status

**v0.0.1** — minimum useful surface. Planned for v0.1:

- `zeroski traces --follow` (WebSocket tail)
- `zeroski login` (browser OAuth / device code)
- `zeroski run <file>.zsk` (local @ pipeline)
- Shell completions (`zeroski completion bash|zsh|fish`)

File issues and feature requests at
<https://github.com/tokencube/zeroski/issues>.

## License

Dual-licensed under **MIT** or **Apache-2.0**, at your option. See
[LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE).