Skip to main content

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}