hyprstream_core/cli/quick.rs
1//! Quick subcommand — orchestrated multi-step workflows.
2//!
3//! These are hand-coded CLI commands that involve multiple RPC calls,
4//! interactive prompts, progress bars, local filesystem access, or
5//! other complex orchestration that cannot be expressed as a single
6//! schema-driven RPC call.
7
8use clap::Subcommand;
9
10use super::commands::policy::PolicyCommand;
11use super::commands::training::TrainingCommand;
12use super::commands::worker::WorkerAction;
13use super::commands::KVQuantArg;
14
15/// Quick workflows — multi-step convenience commands
16#[derive(Subcommand)]
17pub enum QuickCommand {
18 /// Run inference with a model (streaming, stdin support)
19 Infer {
20 /// Model reference (e.g., "Qwen3-4B", "qwen/qwen-2b", "model:branch")
21 model: String,
22
23 /// Prompt text (reads from stdin if not provided)
24 #[arg(short, long)]
25 prompt: Option<String>,
26
27 /// Image file path for multimodal models
28 #[arg(short = 'i', long)]
29 image: Option<String>,
30
31 /// Maximum tokens to generate
32 #[arg(short = 'm', long)]
33 max_tokens: Option<usize>,
34
35 /// Temperature for sampling (0.0 = deterministic)
36 #[arg(short = 't', long)]
37 temperature: Option<f32>,
38
39 /// Top-p (nucleus) sampling
40 #[arg(long)]
41 top_p: Option<f32>,
42
43 /// Top-k sampling
44 #[arg(long)]
45 top_k: Option<usize>,
46
47 /// Repetition penalty (1.0 = no penalty, >1.0 = penalize)
48 #[arg(short = 'r', long)]
49 repeat_penalty: Option<f32>,
50
51 /// Random seed for deterministic generation
52 #[arg(long)]
53 seed: Option<u32>,
54
55 /// Collect full response before printing (default: stream tokens live)
56 #[arg(long)]
57 sync: bool,
58 },
59
60 /// Clone a model repository (with progress, policy support)
61 Clone {
62 /// Git repository URL
63 repo_url: String,
64
65 /// Local name for the model
66 #[arg(long)]
67 name: Option<String>,
68
69 /// Branch, tag, or commit to clone
70 #[arg(long, short = 'b')]
71 branch: Option<String>,
72
73 /// Clone depth (number of commits). Default is 1 for shallow clone.
74 #[arg(long, default_value = "1")]
75 depth: u32,
76
77 /// Clone with full history (overrides --depth)
78 #[arg(long)]
79 full: bool,
80
81 /// Suppress progress output
82 #[arg(long, short = 'q')]
83 quiet: bool,
84
85 /// Verbose output
86 #[arg(long, short = 'v')]
87 verbose: bool,
88
89 /// Apply a policy template to the cloned model
90 #[arg(long)]
91 policy: Option<String>,
92 },
93
94 /// List available models with status and capability detection
95 List {
96 /// Filter by load status (comma-separated, OR semantics, repeatable).
97 /// Valid values: loaded, loading, unloaded
98 /// e.g. -s loaded or -s loaded,loading
99 #[arg(short = 's', long = "status", value_name = "STATUS[,STATUS]...")]
100 status: Vec<String>,
101
102 /// Filter output by column regex (repeatable, AND semantics).
103 /// Patterns are unanchored by default; use ^ and $ to anchor.
104 /// e.g. --filter name=qwen --filter 'domains=llm|vision'
105 /// Valid keys: name, domains, access, ref, commit, size
106 #[arg(long = "filter", value_name = "KEY=REGEX")]
107 filter: Vec<String>,
108 },
109
110 /// Get detailed information about a model
111 Info {
112 /// Model name or reference
113 model: String,
114 /// Show detailed output
115 #[arg(short, long)]
116 verbose: bool,
117 /// Show only adapter information
118 #[arg(long)]
119 adapters_only: bool,
120 },
121
122 /// Show working tree status
123 Status {
124 /// Model reference
125 model: Option<String>,
126 /// Verbose output
127 #[arg(short, long)]
128 verbose: bool,
129 },
130
131 /// Create a new branch (with worktree + policy setup)
132 Branch {
133 /// Model name
134 model: String,
135 /// Branch name
136 name: String,
137 /// Create from specific ref
138 #[arg(long)]
139 from: Option<String>,
140 /// Apply a policy template to the new branch
141 #[arg(long)]
142 policy: Option<String>,
143 },
144
145 /// Switch branches or checkout specific commit/tag
146 Checkout {
147 /// Model name or model reference
148 model: String,
149 /// Git reference to checkout
150 git_ref: Option<String>,
151 /// Create new branch if it doesn't exist
152 #[arg(short = 'b')]
153 create_branch: bool,
154 /// Force checkout
155 #[arg(long)]
156 force: bool,
157 },
158
159 /// Pull changes from remote
160 Pull {
161 /// Model name
162 model: String,
163 /// Remote name (default: origin)
164 remote: Option<String>,
165 /// Branch to pull
166 branch: Option<String>,
167 /// Rebase instead of merge
168 #[arg(long)]
169 rebase: bool,
170 },
171
172 /// Remove a model from the system (interactive confirmation)
173 Remove {
174 /// Model name to remove
175 model: String,
176 /// Force removal without confirmation
177 #[arg(short, long)]
178 force: bool,
179 /// Remove only from registry, keep files
180 #[arg(long)]
181 registry_only: bool,
182 /// Remove files only, keep registry entry
183 #[arg(long)]
184 files_only: bool,
185 },
186
187 /// Load a model into memory with runtime configuration
188 Load {
189 /// Model reference
190 model: String,
191 /// Maximum context length for KV cache allocation
192 #[arg(long, env = "HYPRSTREAM_MAX_CONTEXT")]
193 max_context: Option<usize>,
194 /// KV cache quantization type
195 #[arg(long, value_enum, default_value = "none", env = "HYPRSTREAM_KV_QUANT")]
196 kv_quant: KVQuantArg,
197 /// Wait for model to finish loading, with optional timeout in seconds
198 ///
199 /// Model loading can take 60s+ for large models, exceeding the default
200 /// 30s RPC timeout. With -w/--wait, the CLI subscribes to encrypted
201 /// notification events from the model service and waits asynchronously
202 /// for a model.loaded or model.failed event.
203 ///
204 /// The timeout value is optional (default: 120s). Examples:
205 /// -w Wait up to 120s (default)
206 /// -w 300 Wait up to 300s
207 /// --wait Wait up to 120s
208 /// --wait 60 Wait up to 60s
209 #[arg(short = 'w', long, default_missing_value = "120", num_args = 0..=1)]
210 wait: Option<u64>,
211 },
212
213 /// Unload a model from memory
214 Unload {
215 /// Model reference
216 model: String,
217 },
218
219 /// Listen for real-time events from hyprstream services
220 ///
221 /// The notification system uses end-to-end encrypted broadcast delivery.
222 /// Each subscriber gets a unique Ristretto255 keypair, and the notification
223 /// service acts as a blind relay — it routes encrypted messages without
224 /// being able to read their contents.
225 Notify {
226 #[command(subcommand)]
227 command: NotifyCommand,
228 },
229
230 /// Worktree management
231 Worktree {
232 #[command(subcommand)]
233 command: WorktreeQuickCommand,
234 },
235
236 /// Record changes to the repository
237 #[cfg(feature = "experimental")]
238 Commit {
239 /// Model reference
240 model: String,
241 /// Commit message
242 #[arg(short, long)]
243 message: String,
244 /// Stage all tracked files
245 #[arg(short = 'a', long)]
246 all: bool,
247 /// Stage all files including untracked
248 #[arg(short = 'A', long)]
249 all_untracked: bool,
250 /// Amend the previous commit
251 #[arg(long)]
252 amend: bool,
253 /// Override commit author
254 #[arg(long)]
255 author: Option<String>,
256 /// Override author name
257 #[arg(long)]
258 author_name: Option<String>,
259 /// Override author email
260 #[arg(long)]
261 author_email: Option<String>,
262 /// Allow empty commits
263 #[arg(long)]
264 allow_empty: bool,
265 /// Show what would be committed without committing
266 #[arg(long)]
267 dry_run: bool,
268 /// Show diff of changes being committed
269 #[arg(short = 'v', long)]
270 verbose: bool,
271 },
272
273 /// Promote the node-local upper layer into a content-addressed registry
274 /// commit and advance the atproto pointer (#394).
275 ///
276 /// This is the writable-union promote primitive: it snapshots buffered
277 /// edits (stageAll + commit) into an immutable, deterministic git commit,
278 /// then updates the federated pointer record. See `git::promote` for the
279 /// eventual-consistency contract.
280 #[cfg(feature = "experimental")]
281 Promote {
282 /// Model reference (repo name).
283 model: String,
284 /// Worktree / branch to promote.
285 branch: String,
286 /// Override author name (defaults to the verified subject).
287 #[arg(long)]
288 author_name: Option<String>,
289 /// Override author email (defaults to the subject's account DID).
290 #[arg(long)]
291 author_email: Option<String>,
292 },
293
294 /// Push changes to remote
295 #[cfg(feature = "experimental")]
296 Push {
297 /// Model name
298 model: String,
299 /// Remote name (default: origin)
300 remote: Option<String>,
301 /// Branch to push
302 branch: Option<String>,
303 /// Set upstream
304 #[arg(short = 'u', long)]
305 set_upstream: bool,
306 /// Force push
307 #[arg(long)]
308 force: bool,
309 },
310
311 /// Merge branches
312 #[cfg(feature = "experimental")]
313 Merge {
314 /// Target model and branch
315 target: String,
316 /// Branch/ref to merge into target
317 source: String,
318 #[arg(long, conflicts_with = "no_ff", conflicts_with = "ff_only")]
319 ff: bool,
320 #[arg(long, conflicts_with = "ff", conflicts_with = "ff_only")]
321 no_ff: bool,
322 #[arg(long, conflicts_with = "ff", conflicts_with = "no_ff")]
323 ff_only: bool,
324 #[arg(long)]
325 no_commit: bool,
326 #[arg(long)]
327 squash: bool,
328 #[arg(short, long)]
329 message: Option<String>,
330 #[arg(long, conflicts_with_all = ["continue_merge", "quit"])]
331 abort: bool,
332 #[arg(long = "continue", conflicts_with_all = ["abort", "quit"])]
333 continue_merge: bool,
334 #[arg(long, conflicts_with_all = ["abort", "continue_merge"])]
335 quit: bool,
336 #[arg(long)]
337 no_stat: bool,
338 #[arg(short = 'q', long)]
339 quiet: bool,
340 #[arg(short = 'v', long)]
341 verbose: bool,
342 #[arg(long, short = 's')]
343 strategy: Option<String>,
344 #[arg(long, short = 'X')]
345 strategy_option: Vec<String>,
346 #[arg(long)]
347 allow_unrelated_histories: bool,
348 #[arg(long)]
349 no_verify: bool,
350 },
351
352 /// Worker (sandbox/container) management commands
353 ///
354 /// Multi-step orchestrated workflows for Kata VMs and OCI containers.
355 /// Commands involve multiple RPC calls, service bootstrapping, and
356 /// interactive terminal I/O.
357 Worker {
358 #[command(subcommand)]
359 command: WorkerAction,
360 },
361
362 /// Training workflows (multi-step, GPU, streaming)
363 Training(TrainingCommand),
364
365 /// Policy management commands (interactive, multi-step)
366 Policy {
367 #[command(subcommand)]
368 command: PolicyCommand,
369 },
370
371 /// Remote management commands
372 Remote {
373 #[command(subcommand)]
374 command: RemoteQuickCommand,
375 },
376}
377
378/// Worktree subcommands for quick workflows
379#[derive(Subcommand)]
380pub enum WorktreeQuickCommand {
381 /// Create a worktree from an existing branch
382 Add {
383 /// Model name
384 model: String,
385 /// Branch name
386 branch: String,
387 /// Apply a policy template
388 #[arg(long)]
389 policy: Option<String>,
390 },
391
392 /// List all worktrees for a model
393 List {
394 /// Model name
395 model: String,
396 /// Show all branches
397 #[arg(long)]
398 all: bool,
399 },
400
401 /// Show detailed information about a worktree
402 Info {
403 /// Model name
404 model: String,
405 /// Branch/worktree name
406 branch: String,
407 },
408
409 /// Remove a worktree
410 Remove {
411 /// Model name
412 model: String,
413 /// Branch/worktree name
414 branch: String,
415 /// Force removal without confirmation
416 #[arg(short, long)]
417 force: bool,
418 },
419}
420
421/// Notification subcommands
422#[derive(Subcommand)]
423pub enum NotifyCommand {
424 /// Verify authenticated native Event access by receiving the system track.
425 Probe {
426 /// Maximum seconds for discovery, admission and authorized delivery.
427 #[arg(long, default_value = "10")]
428 timeout: u64,
429 },
430 /// Subscribe to real-time events matching a scope pattern
431 ///
432 /// Opens an encrypted notification channel and prints events as they arrive.
433 /// The scope pattern uses dot-notation with wildcards:
434 ///
435 /// serve:model:* — All model lifecycle events (load, unload, fail)
436 /// serve:model:qwen3 — Events for a specific model
437 /// infer:model:* — Inference completion/failure events
438 /// train:model:* — Training job events
439 ///
440 /// How it works:
441 ///
442 /// 1. Generates an ephemeral Ristretto255 keypair for this session
443 /// 2. Registers the public key with NotificationService (via RPC)
444 /// 3. Connects a ZMQ SUB socket to the assigned StreamService topic
445 /// 4. For each received message:
446 /// a. Parses the StreamBlock envelope (HMAC-verified transport)
447 /// b. Extracts the NotificationBlock (Cap'n Proto)
448 /// c. Performs blinding-aware DH: shared = (secret + r) × publisher_pub
449 /// d. Derives enc_key + mac_key from the shared secret
450 /// e. Verifies the publisher's one-shot MAC
451 /// f. Unwraps the per-subscriber AES-256-GCM key capsule
452 /// g. Decrypts the payload with AAD binding to intent + scope
453 /// 5. Prints the decrypted EventEnvelope
454 ///
455 /// The NotificationService never sees plaintext — it only routes encrypted
456 /// capsules to pre-registered subscriber topics.
457 Subscribe {
458 /// Scope pattern to match (e.g., "serve:model:*", "train:model:*")
459 pattern: String,
460 /// Output events as JSON (one per line, suitable for piping)
461 #[arg(long)]
462 json: bool,
463 /// Stop after N seconds (0 = run until interrupted)
464 #[arg(long, default_value = "0")]
465 timeout: u64,
466 /// Stop after receiving N events (0 = unlimited)
467 #[arg(long, short = 'n', default_value = "0")]
468 count: u64,
469 },
470}
471
472/// Remote management subcommands for quick workflows
473#[derive(Subcommand)]
474pub enum RemoteQuickCommand {
475 /// Add a new remote
476 Add {
477 /// Model name
478 model: String,
479 /// Remote name
480 name: String,
481 /// Remote URL
482 url: String,
483 },
484
485 /// List all remotes
486 List {
487 /// Model name
488 model: String,
489 /// Show verbose output
490 #[arg(short, long)]
491 verbose: bool,
492 },
493
494 /// Remove a remote
495 Remove {
496 /// Model name
497 model: String,
498 /// Remote name to remove
499 name: String,
500 },
501
502 /// Change a remote's URL
503 SetUrl {
504 /// Model name
505 model: String,
506 /// Remote name
507 name: String,
508 /// New URL
509 url: String,
510 },
511
512 /// Rename a remote
513 Rename {
514 /// Model name
515 model: String,
516 /// Current remote name
517 old_name: String,
518 /// New remote name
519 new_name: String,
520 },
521}