snapshot of https://github.com/mountain-loop/yaak.git (main, 2026-09-23; blobs > 131072B omitted)

crates-cli/yaak-cli/src/cli.rs

@@ -0,0 +1,622 @@
+use clap::{Args, Parser, Subcommand, ValueEnum};
+use std::path::PathBuf;
+
+pub const AGENT_HINTS: &str = r#"Agent Hints:
+  - Template variable syntax is ${[ my_var ]}, not {{ ... }}
+  - Template function syntax is ${[ namespace.my_func(a='aaa',b='bbb') ]}
+  - View JSONSchema for models before creating or updating (eg. `yaak request schema http`)
+  - Deletion requires confirmation (--yes for non-interactive environments)"#;
+
+#[derive(Parser)]
+#[command(name = "yaak")]
+#[command(about = "Yaak CLI - API client from the command line")]
+#[command(version = crate::version::cli_version())]
+#[command(disable_help_subcommand = true)]
+pub struct Cli {
+    /// Use a custom data directory
+    #[arg(long, global = true)]
+    pub data_dir: Option<PathBuf>,
+
+    /// Environment ID to use for variable substitution
+    #[arg(long, short, global = true)]
+    pub environment: Option<String>,
+
+    /// Cookie jar ID to use when sending requests
+    #[arg(long = "cookie-jar", global = true, value_name = "COOKIE_JAR_ID")]
+    pub cookie_jar: Option<String>,
+
+    /// Enable verbose send output (events and streamed response body)
+    #[arg(long, short, global = true)]
+    pub verbose: bool,
+
+    /// Enable CLI logging; optionally set level (error|warn|info|debug|trace)
+    #[arg(long, global = true, value_name = "LEVEL", num_args = 0..=1, ignore_case = true)]
+    pub log: Option<Option<LogLevel>>,
+
+    #[command(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Subcommand)]
+pub enum Commands {
+    /// Install Yaak skills for AI coding agents
+    Agent(AgentArgs),
+
+    /// Authentication commands
+    Auth(AuthArgs),
+
+    /// Import API data from Yaak, OpenAPI, Postman, Insomnia, Swagger, or cURL
+    Import(ImportArgs),
+
+    /// Export Yaak workspace data
+    Export(ExportArgs),
+
+    /// Plugin development and publishing commands
+    Plugin(PluginArgs),
+
+    #[command(hide = true)]
+    Build(PluginPathArg),
+
+    #[command(hide = true)]
+    Dev(PluginPathArg),
+
+    /// Backward-compatible alias for `plugin generate`
+    #[command(hide = true)]
+    Generate(GenerateArgs),
+
+    /// Backward-compatible alias for `plugin publish`
+    #[command(hide = true)]
+    Publish(PluginPathArg),
+
+    /// Send a request, folder, or workspace by ID
+    Send(SendArgs),
+
+    /// Cookie jar commands
+    CookieJar(CookieJarArgs),
+
+    /// Workspace commands
+    Workspace(WorkspaceArgs),
+
+    /// Request commands
+    Request(RequestArgs),
+
+    /// Folder commands
+    Folder(FolderArgs),
+
+    /// Environment commands
+    Environment(EnvironmentArgs),
+
+    /// Template function commands
+    #[command(alias = "func")]
+    TemplateFunction(TemplateFunctionArgs),
+
+    /// Response commands
+    Response(ResponseArgs),
+}
+
+#[derive(Args)]
+pub struct ResponseArgs {
+    #[command(subcommand)]
+    pub command: ResponseCommands,
+}
+
+#[derive(Subcommand)]
+pub enum ResponseCommands {
+    /// List stored responses for a request or workspace
+    List {
+        /// Request or workspace ID (optional when exactly one workspace exists)
+        id: Option<String>,
+
+        /// Maximum number of responses to return, newest first
+        #[arg(long)]
+        limit: Option<u64>,
+    },
+
+    /// Show a response as JSON, including status, timing, and headers
+    Show {
+        /// Response ID, or a request ID to use its most recent response
+        id: String,
+    },
+
+    /// Write a stored response body to stdout
+    Body {
+        /// Response ID, or a request ID to use its most recent response
+        id: String,
+    },
+
+    /// Delete stored responses for a request or workspace
+    Delete {
+        /// Request or workspace ID
+        id: String,
+
+        /// Skip confirmation prompt
+        #[arg(short, long)]
+        yes: bool,
+    },
+}
+
+#[derive(Args)]
+pub struct TemplateFunctionArgs {
+    #[command(subcommand)]
+    pub command: TemplateFunctionCommands,
+}
+
+#[derive(Subcommand)]
+pub enum TemplateFunctionCommands {
+    /// List template functions provided by installed plugins
+    List {
+        /// Only show functions whose name contains this text
+        #[arg(value_name = "FILTER")]
+        filter: Option<String>,
+    },
+
+    /// Show a template function's arguments as JSON
+    Show {
+        /// Template function name (for example: response.body.path)
+        name: String,
+
+        /// Pretty-print JSON output
+        #[arg(long)]
+        pretty: bool,
+    },
+}
+
+#[derive(Args)]
+pub struct AgentArgs {
+    #[command(subcommand)]
+    pub command: AgentCommands,
+}
+
+#[derive(Subcommand)]
+pub enum AgentCommands {
+    /// Install the Yaak skill so coding agents know how to drive the CLI
+    #[command(alias = "update", alias = "add")]
+    Install {
+        /// Install for specific agents instead of all detected ones
+        #[arg(long = "agent", value_name = "AGENT")]
+        agent: Option<Vec<String>>,
+    },
+
+    /// Remove the Yaak skill
+    #[command(alias = "uninstall", alias = "rm")]
+    Remove {
+        /// Remove for specific agents instead of all detected ones
+        #[arg(long = "agent", value_name = "AGENT")]
+        agent: Option<Vec<String>>,
+    },
+}
+
+#[derive(Args)]
+pub struct SendArgs {
+    /// Request, folder, or workspace ID
+    pub id: String,
+
+    /// Execute requests in parallel
+    #[arg(long)]
+    pub parallel: bool,
+
+    /// Stop on first request failure when sending folders/workspaces
+    #[arg(long, conflicts_with = "parallel")]
+    pub fail_fast: bool,
+}
+
+#[derive(Args)]
+pub struct ImportArgs {
+    /// Path to the file to import
+    pub file: PathBuf,
+
+    /// Existing workspace ID to import into when supported by the importer
+    #[arg(long = "workspace-id", value_name = "WORKSPACE_ID")]
+    pub workspace_id: Option<String>,
+}
+
+#[derive(Args)]
+pub struct ExportArgs {
+    /// Path to write the Yaak export JSON file
+    pub file: PathBuf,
+
+    /// Workspace IDs to export (defaults to the only workspace when exactly one exists)
+    #[arg(value_name = "WORKSPACE_ID")]
+    pub workspace_ids: Vec<String>,
+
+    /// Export all workspaces
+    #[arg(long, conflicts_with = "workspace_ids")]
+    pub all: bool,
+
+    /// Include private environments in the export
+    #[arg(long)]
+    pub include_private_environments: bool,
+}
+
+#[derive(Args)]
+#[command(disable_help_subcommand = true)]
+pub struct CookieJarArgs {
+    #[command(subcommand)]
+    pub command: CookieJarCommands,
+}
+
+#[derive(Subcommand)]
+pub enum CookieJarCommands {
+    /// List cookie jars in a workspace
+    List {
+        /// Workspace ID (optional when exactly one workspace exists)
+        workspace_id: Option<String>,
+    },
+}
+
+#[derive(Args)]
+#[command(disable_help_subcommand = true)]
+pub struct WorkspaceArgs {
+    #[command(subcommand)]
+    pub command: WorkspaceCommands,
+}
+
+#[derive(Subcommand)]
+pub enum WorkspaceCommands {
+    /// List all workspaces
+    List,
+
+    /// Output JSON schema for workspace create/update payloads
+    Schema {
+        /// Pretty-print schema JSON output
+        #[arg(long)]
+        pretty: bool,
+    },
+
+    /// Show a workspace as JSON
+    Show {
+        /// Workspace ID
+        workspace_id: String,
+    },
+
+    /// Create a workspace
+    Create {
+        /// Workspace name
+        #[arg(short, long)]
+        name: Option<String>,
+
+        /// JSON payload
+        #[arg(long, conflicts_with = "json_input")]
+        json: Option<String>,
+
+        /// JSON payload shorthand
+        #[arg(value_name = "JSON", conflicts_with = "json")]
+        json_input: Option<String>,
+    },
+
+    /// Update a workspace
+    Update {
+        /// JSON payload
+        #[arg(long, conflicts_with = "json_input")]
+        json: Option<String>,
+
+        /// JSON payload shorthand
+        #[arg(value_name = "JSON", conflicts_with = "json")]
+        json_input: Option<String>,
+    },
+
+    /// Delete a workspace
+    Delete {
+        /// Workspace ID
+        workspace_id: String,
+
+        /// Skip confirmation prompt
+        #[arg(short, long)]
+        yes: bool,
+    },
+}
+
+#[derive(Args)]
+#[command(disable_help_subcommand = true)]
+pub struct RequestArgs {
+    #[command(subcommand)]
+    pub command: RequestCommands,
+}
+
+#[derive(Subcommand)]
+pub enum RequestCommands {
+    /// List requests in a workspace
+    List {
+        /// Workspace ID (optional when exactly one workspace exists)
+        workspace_id: Option<String>,
+    },
+
+    /// Show a request as JSON
+    Show {
+        /// Request ID
+        request_id: String,
+    },
+
+    /// Send a request by ID
+    Send {
+        /// Request ID
+        request_id: String,
+    },
+
+    /// Output JSON schema for request create/update payloads
+    Schema {
+        #[arg(value_enum)]
+        request_type: RequestSchemaType,
+
+        /// Pretty-print schema JSON output
+        #[arg(long)]
+        pretty: bool,
+    },
+
+    /// Create a new HTTP request
+    Create {
+        /// Workspace ID (or positional JSON payload shorthand)
+        workspace_id: Option<String>,
+
+        /// Request name
+        #[arg(short, long)]
+        name: Option<String>,
+
+        /// HTTP method
+        #[arg(short, long)]
+        method: Option<String>,
+
+        /// URL
+        #[arg(short, long)]
+        url: Option<String>,
+
+        /// JSON payload
+        #[arg(long)]
+        json: Option<String>,
+    },
+
+    /// Update an HTTP request
+    Update {
+        /// JSON payload
+        #[arg(long, conflicts_with = "json_input")]
+        json: Option<String>,
+
+        /// JSON payload shorthand
+        #[arg(value_name = "JSON", conflicts_with = "json")]
+        json_input: Option<String>,
+    },
+
+    /// Delete a request
+    Delete {
+        /// Request ID
+        request_id: String,
+
+        /// Skip confirmation prompt
+        #[arg(short, long)]
+        yes: bool,
+    },
+}
+
+#[derive(Clone, Copy, Debug, ValueEnum)]
+pub enum RequestSchemaType {
+    Http,
+    Grpc,
+    Websocket,
+}
+
+#[derive(Clone, Copy, Debug, ValueEnum)]
+pub enum LogLevel {
+    Error,
+    Warn,
+    Info,
+    Debug,
+    Trace,
+}
+
+impl LogLevel {
+    pub fn as_filter(self) -> log::LevelFilter {
+        match self {
+            LogLevel::Error => log::LevelFilter::Error,
+            LogLevel::Warn => log::LevelFilter::Warn,
+            LogLevel::Info => log::LevelFilter::Info,
+            LogLevel::Debug => log::LevelFilter::Debug,
+            LogLevel::Trace => log::LevelFilter::Trace,
+        }
+    }
+}
+
+#[derive(Args)]
+#[command(disable_help_subcommand = true)]
+pub struct FolderArgs {
+    #[command(subcommand)]
+    pub command: FolderCommands,
+}
+
+#[derive(Subcommand)]
+pub enum FolderCommands {
+    /// List folders in a workspace
+    List {
+        /// Workspace ID (optional when exactly one workspace exists)
+        workspace_id: Option<String>,
+    },
+
+    /// Output JSON schema for folder create/update payloads
+    Schema {
+        /// Pretty-print schema JSON output
+        #[arg(long)]
+        pretty: bool,
+    },
+
+    /// Show a folder as JSON
+    Show {
+        /// Folder ID
+        folder_id: String,
+    },
+
+    /// Create a folder
+    Create {
+        /// Workspace ID (or positional JSON payload shorthand)
+        workspace_id: Option<String>,
+
+        /// Folder name
+        #[arg(short, long)]
+        name: Option<String>,
+
+        /// JSON payload
+        #[arg(long)]
+        json: Option<String>,
+    },
+
+    /// Update a folder
+    Update {
+        /// JSON payload
+        #[arg(long, conflicts_with = "json_input")]
+        json: Option<String>,
+
+        /// JSON payload shorthand
+        #[arg(value_name = "JSON", conflicts_with = "json")]
+        json_input: Option<String>,
+    },
+
+    /// Delete a folder
+    Delete {
+        /// Folder ID
+        folder_id: String,
+
+        /// Skip confirmation prompt
+        #[arg(short, long)]
+        yes: bool,
+    },
+}
+
+#[derive(Args)]
+#[command(disable_help_subcommand = true)]
+pub struct EnvironmentArgs {
+    #[command(subcommand)]
+    pub command: EnvironmentCommands,
+}
+
+#[derive(Subcommand)]
+pub enum EnvironmentCommands {
+    /// List environments in a workspace
+    List {
+        /// Workspace ID (optional when exactly one workspace exists)
+        workspace_id: Option<String>,
+    },
+
+    /// Output JSON schema for environment create/update payloads
+    Schema {
+        /// Pretty-print schema JSON output
+        #[arg(long)]
+        pretty: bool,
+    },
+
+    /// Show an environment as JSON
+    Show {
+        /// Environment ID
+        environment_id: String,
+    },
+
+    /// Create an environment
+    #[command(after_help = r#"Modes (choose one):
+  1) yaak environment create <workspace_id> --name <name>
+  2) yaak environment create --json '{"workspaceId":"wk_abc","name":"Production"}'
+  3) yaak environment create '{"workspaceId":"wk_abc","name":"Production"}'
+  4) yaak environment create <workspace_id> --json '{"name":"Production"}'
+"#)]
+    Create {
+        /// Workspace ID for flag-based mode, or positional JSON payload shorthand
+        #[arg(value_name = "WORKSPACE_ID_OR_JSON")]
+        workspace_id: Option<String>,
+
+        /// Environment name
+        #[arg(short, long)]
+        name: Option<String>,
+
+        /// JSON payload (use instead of WORKSPACE_ID/--name)
+        #[arg(long)]
+        json: Option<String>,
+    },
+
+    /// Update an environment
+    Update {
+        /// JSON payload
+        #[arg(long, conflicts_with = "json_input")]
+        json: Option<String>,
+
+        /// JSON payload shorthand
+        #[arg(value_name = "JSON", conflicts_with = "json")]
+        json_input: Option<String>,
+    },
+
+    /// Delete an environment
+    Delete {
+        /// Environment ID
+        environment_id: String,
+
+        /// Skip confirmation prompt
+        #[arg(short, long)]
+        yes: bool,
+    },
+}
+
+#[derive(Args)]
+#[command(disable_help_subcommand = true)]
+pub struct AuthArgs {
+    #[command(subcommand)]
+    pub command: AuthCommands,
+}
+
+#[derive(Subcommand)]
+pub enum AuthCommands {
+    /// Login to Yaak via web browser
+    Login,
+
+    /// Sign out of the Yaak CLI
+    Logout,
+
+    /// Print the current logged-in user's info
+    Whoami,
+}
+
+#[derive(Args)]
+#[command(disable_help_subcommand = true)]
+pub struct PluginArgs {
+    #[command(subcommand)]
+    pub command: PluginCommands,
+}
+
+#[derive(Subcommand)]
+pub enum PluginCommands {
+    /// Transpile code into a runnable plugin bundle
+    Build(PluginPathArg),
+
+    /// Build plugin bundle continuously when the filesystem changes
+    Dev(PluginPathArg),
+
+    /// Generate a "Hello World" Yaak plugin
+    Generate(GenerateArgs),
+
+    /// Install a plugin from a local directory or from the registry
+    Install(InstallPluginArgs),
+
+    /// Generate plugin metadata for the registry
+    #[command(hide = true)]
+    Metadata(PluginPathArg),
+
+    /// Publish a Yaak plugin version to the plugin registry
+    Publish(PluginPathArg),
+}
+
+#[derive(Args, Clone)]
+pub struct PluginPathArg {
+    /// Path to plugin directory (defaults to current working directory)
+    pub path: Option<PathBuf>,
+}
+
+#[derive(Args, Clone)]
+pub struct GenerateArgs {
+    /// Plugin name (defaults to a generated name in interactive mode)
+    #[arg(long)]
+    pub name: Option<String>,
+
+    /// Output directory for the generated plugin (defaults to ./<name> in interactive mode)
+    #[arg(long)]
+    pub dir: Option<PathBuf>,
+}
+
+#[derive(Args, Clone)]
+pub struct InstallPluginArgs {
+    /// Local plugin directory path, or registry plugin spec (@org/plugin[@version])
+    pub source: String,
+}

crates-cli/yaak-cli/src/commands/agent.rs

@@ -0,0 +1,269 @@
+use crate::cli::{AgentArgs, AgentCommands};
+use crate::ui;
+use crate::version;
+use include_dir::{Dir, include_dir};
+use std::fs;
+use std::path::{Path, PathBuf};
+
+static SKILL_DIR: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/skills/use-yaak");
+
+const SKILL_NAME: &str = "use-yaak";
+
+/// Substituted at install time so the installed skill records which CLI wrote it,
+/// letting `--help` tell the user when an upgrade has left their copy behind.
+const VERSION_PLACEHOLDER: &str = "__YAAK_CLI_VERSION__";
+const VERSION_MARKER: &str = "yaak-cli-version:";
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+/// A coding tool that reads skills from a directory in the user's home.
+struct Target {
+    /// Display name used in output.
+    label: &'static str,
+    /// Directory holding all skills for this tool (`…/skills`).
+    skills_dir: PathBuf,
+}
+
+pub fn run(args: AgentArgs) -> i32 {
+    let result = match args.command {
+        AgentCommands::Install { agent } => install(agent),
+        AgentCommands::Remove { agent } => remove(agent),
+    };
+
+    match result {
+        Ok(()) => 0,
+        Err(error) => {
+            ui::error(&error);
+            1
+        }
+    }
+}
+
+fn install(agent: Option<Vec<String>>) -> CommandResult {
+    let targets = resolve_targets(agent)?;
+
+    let mut installed = 0usize;
+    for target in &targets {
+        let dir = target.skills_dir.join(SKILL_NAME);
+        match write_skill(&dir) {
+            Ok(()) => {
+                installed += 1;
+                ui::success(&format!("{} -> {}", target.label, dir.display()));
+            }
+            Err(error) => ui::warning_stderr(&format!("{}: {}", target.label, error)),
+        }
+    }
+
+    if installed == 0 {
+        return Err("Failed to install the Yaak skill anywhere".to_string());
+    }
+
+    ui::info("Restart your coding tool to pick up the skill");
+    Ok(())
+}
+
+fn remove(agent: Option<Vec<String>>) -> CommandResult {
+    let targets = resolve_targets(agent)?;
+
+    let mut removed = 0usize;
+    for target in &targets {
+        let dir = target.skills_dir.join(SKILL_NAME);
+        if !dir.exists() {
+            continue;
+        }
+        match fs::remove_dir_all(&dir) {
+            Ok(()) => {
+                removed += 1;
+                ui::success(&format!("Removed {}", dir.display()));
+            }
+            Err(error) => {
+                ui::warning_stderr(&format!("Failed to remove {}: {error}", dir.display()))
+            }
+        }
+    }
+
+    if removed == 0 {
+        ui::info("No Yaak skill was installed");
+    }
+    Ok(())
+}
+
+/// The skill directory belongs to the CLI, so every install overwrites what is there
+/// and prunes what this version no longer ships. Preserving local edits would be worse
+/// than losing them: an edited file would be skipped by every future install and go
+/// stale forever, against a CLI that keeps changing.
+///
+/// NOTE: atomicity is per file, not for the install as a whole. That is total today
+/// because the skill is a single file, but adding a second one would mean a reader
+/// could catch a mix of old and new files. Replacing the directory as a unit is not an
+/// option (`rename` refuses a non-empty destination), so a multi-file skill would need
+/// the published path to become a symlink swapped between versioned directories.
+fn write_skill(dir: &Path) -> CommandResult {
+    fs::create_dir_all(dir).map_err(|e| format!("Failed to create {}: {e}", dir.display()))?;
+
+    let mut written = Vec::new();
+    for file in walk(&SKILL_DIR) {
+        let relative = file.path().to_path_buf();
+        let destination = dir.join(&relative);
+        if let Some(parent) = destination.parent() {
+            fs::create_dir_all(parent)
+                .map_err(|e| format!("Failed to create {}: {e}", parent.display()))?;
+        }
+
+        let contents = stamp_version(file.contents());
+        write_atomic(&destination, &contents)?;
+        written.push(relative);
+    }
+
+    prune_unshipped(dir, &written);
+    Ok(())
+}
+
+/// Write via a sibling temp file and rename over the destination. `rename` replaces an
+/// existing file atomically, so a reader sees either the old copy or the new one, and a
+/// crash part way through cannot leave a half-written skill behind.
+fn write_atomic(destination: &Path, contents: &[u8]) -> CommandResult {
+    let parent = destination
+        .parent()
+        .ok_or_else(|| format!("Invalid skill path {}", destination.display()))?;
+    let name = destination
+        .file_name()
+        .and_then(|n| n.to_str())
+        .ok_or_else(|| format!("Invalid skill path {}", destination.display()))?;
+    let temp = parent.join(format!(".{name}.tmp-{}", std::process::id()));
+
+    fs::write(&temp, contents)
+        .map_err(|e| format!("Failed to write {}: {e}", destination.display()))?;
+
+    match fs::rename(&temp, destination) {
+        Ok(()) => Ok(()),
+        Err(error) => {
+            let _ = fs::remove_file(&temp);
+            Err(format!("Failed to write {}: {error}", destination.display()))
+        }
+    }
+}
+
+/// Stamp the running version into the skill so it carries its own provenance.
+fn stamp_version(contents: &[u8]) -> Vec<u8> {
+    match std::str::from_utf8(contents) {
+        Ok(text) => text.replace(VERSION_PLACEHOLDER, version::cli_version()).into_bytes(),
+        Err(_) => contents.to_vec(),
+    }
+}
+
+/// Drop anything this version does not ship, so files an older version wrote (or a
+/// leftover temp file) cannot linger beside the refreshed skill.
+fn prune_unshipped(dir: &Path, written: &[PathBuf]) {
+    let Ok(entries) = fs::read_dir(dir) else {
+        return;
+    };
+
+    for entry in entries.flatten() {
+        let path = entry.path();
+        let Ok(relative) = path.strip_prefix(dir) else {
+            continue;
+        };
+        if written.iter().any(|w| w == relative || w.starts_with(relative)) {
+            continue;
+        }
+        if path.is_dir() {
+            let _ = fs::remove_dir_all(&path);
+        } else {
+            let _ = fs::remove_file(&path);
+        }
+    }
+}
+
+/// Read the version an installed skill was stamped with.
+fn installed_version(dir: &Path) -> Option<String> {
+    let text = fs::read_to_string(dir.join("SKILL.md")).ok()?;
+    text.lines()
+        .find_map(|line| line.trim().strip_prefix(VERSION_MARKER))
+        .map(|v| v.trim().to_string())
+        .filter(|v| !v.is_empty() && v != VERSION_PLACEHOLDER)
+}
+
+/// Health summary appended to root `--help`, so an agent can notice in one command
+/// that an upgraded CLI has left the installed skill behind. Silent when nothing is
+/// installed anywhere, to avoid nagging users who do not use agent tooling.
+pub fn help_section() -> Option<String> {
+    let targets = resolve_targets(None).ok()?;
+    let current = version::cli_version();
+
+    let mut stale = Vec::new();
+    let mut installed = 0usize;
+    for target in &targets {
+        let dir = target.skills_dir.join(SKILL_NAME);
+        if !dir.join("SKILL.md").exists() {
+            continue;
+        }
+        installed += 1;
+
+        let found = installed_version(&dir).unwrap_or_default();
+        if found != current {
+            let found = if found.is_empty() { "unknown".to_string() } else { found };
+            stale.push(format!("{} ({found})", target.label));
+        }
+    }
+
+    if installed == 0 {
+        return None;
+    }
+
+    if stale.is_empty() {
+        return Some(format!(
+            "Agent tooling:\n  Yaak skill is installed and up to date ({current})"
+        ));
+    }
+
+    Some(format!(
+        "Agent tooling:\n  Yaak skill is out of date for {} — CLI is {current}\n  Run `yaak agent install`, then restart your coding tool",
+        stale.join(", ")
+    ))
+}
+
+/// Flatten the embedded skill directory into its files, recursing into subdirectories.
+fn walk<'a>(dir: &'a Dir<'a>) -> Vec<&'a include_dir::File<'a>> {
+    let mut files: Vec<_> = dir.files().collect();
+    for child in dir.dirs() {
+        files.extend(walk(child));
+    }
+    files
+}
+
+/// `~/.agents/skills` is the cross-tool location and is always written. Tool-specific
+/// directories are written only when that tool is already set up on this machine, so
+/// installing never creates a config directory for a tool the user does not use.
+fn resolve_targets(requested: Option<Vec<String>>) -> CommandResult<Vec<Target>> {
+    let home = dirs::home_dir().ok_or("Could not determine home directory")?;
+
+    let known: Vec<(&str, PathBuf, PathBuf)> = vec![
+        ("agents", home.join(".agents"), home.join(".agents").join("skills")),
+        ("claude-code", home.join(".claude"), home.join(".claude").join("skills")),
+        ("cursor", home.join(".cursor"), home.join(".cursor").join("skills")),
+        ("codex", home.join(".codex"), home.join(".codex").join("skills")),
+        ("opencode", home.join(".opencode"), home.join(".opencode").join("skills")),
+    ];
+
+    if let Some(requested) = requested {
+        let mut targets = Vec::new();
+        for name in requested {
+            let found =
+                known.iter().find(|(label, _, _)| *label == name.as_str()).ok_or_else(|| {
+                    let names: Vec<_> = known.iter().map(|(l, _, _)| *l).collect();
+                    format!("Unknown agent '{name}'. Known agents: {}", names.join(", "))
+                })?;
+            targets.push(Target { label: found.0, skills_dir: found.2.clone() });
+        }
+        return Ok(targets);
+    }
+
+    let targets: Vec<Target> = known
+        .into_iter()
+        .filter(|(label, marker, _)| *label == "agents" || marker.exists())
+        .map(|(label, _, skills_dir)| Target { label, skills_dir })
+        .collect();
+
+    Ok(targets)
+}

crates-cli/yaak-cli/src/commands/auth.rs

@@ -0,0 +1,596 @@
+use crate::cli::{AuthArgs, AuthCommands};
+use crate::ui;
+use crate::utils::http;
+use base64::Engine as _;
+use keyring::Entry;
+use rand::RngCore;
+use rand::rngs::OsRng;
+use reqwest::Url;
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use std::io::{self, IsTerminal, Write};
+use std::time::Duration;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpListener, TcpStream};
+
+const OAUTH_CLIENT_ID: &str = "a1fe44800c2d7e803cad1b4bf07a291c";
+const KEYRING_USER: &str = "yaak";
+const AUTH_TIMEOUT: Duration = Duration::from_secs(300);
+const CALLBACK_READ_TIMEOUT: Duration = Duration::from_secs(10);
+const MAX_REQUEST_BYTES: usize = 16 * 1024;
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum Environment {
+    Production,
+    Staging,
+    Development,
+}
+
+impl Environment {
+    fn app_base_url(self) -> &'static str {
+        match self {
+            Environment::Production => "https://yaak.app",
+            Environment::Staging => "https://todo.yaak.app",
+            Environment::Development => "http://localhost:9444",
+        }
+    }
+
+    fn api_base_url(self) -> &'static str {
+        match self {
+            Environment::Production => "https://api.yaak.app",
+            Environment::Staging => "https://todo.yaak.app",
+            Environment::Development => "http://localhost:9444",
+        }
+    }
+
+    fn keyring_service(self) -> &'static str {
+        match self {
+            Environment::Production => "app.yaak.cli.Token",
+            Environment::Staging => "app.yaak.cli.staging.Token",
+            Environment::Development => "app.yaak.cli.dev.Token",
+        }
+    }
+}
+
+struct OAuthFlow {
+    app_base_url: String,
+    auth_url: Url,
+    token_url: String,
+    redirect_url: String,
+    state: String,
+    code_verifier: String,
+}
+
+pub async fn run(args: AuthArgs) -> i32 {
+    let result = match args.command {
+        AuthCommands::Login => login().await,
+        AuthCommands::Logout => logout(),
+        AuthCommands::Whoami => whoami().await,
+    };
+
+    match result {
+        Ok(()) => 0,
+        Err(error) => {
+            ui::error(&error);
+            1
+        }
+    }
+}
+
+async fn login() -> CommandResult {
+    let environment = current_environment();
+
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .map_err(|e| format!("Failed to start OAuth callback server: {e}"))?;
+    let port = listener
+        .local_addr()
+        .map_err(|e| format!("Failed to determine callback server port: {e}"))?
+        .port();
+
+    let oauth = build_oauth_flow(environment, port)?;
+
+    ui::info(&format!("Initiating login to {}", oauth.auth_url));
+    if !confirm_open_browser()? {
+        ui::info("Login canceled");
+        return Ok(());
+    }
+
+    if let Err(err) = webbrowser::open(oauth.auth_url.as_ref()) {
+        ui::warning(&format!("Failed to open browser: {err}"));
+        ui::info(&format!("Open this URL manually:\n{}", oauth.auth_url));
+    }
+    ui::info("Waiting for authentication...");
+
+    let code = tokio::select! {
+        result = receive_oauth_code(listener, &oauth.state, &oauth.app_base_url) => result?,
+        _ = tokio::signal::ctrl_c() => {
+            return Err("Interrupted by user".to_string());
+        }
+        _ = tokio::time::sleep(AUTH_TIMEOUT) => {
+            return Err("Timeout waiting for authentication".to_string());
+        }
+    };
+
+    let token = exchange_access_token(&oauth, &code).await?;
+    store_auth_token(environment, &token)?;
+    ui::success("Authentication successful!");
+    Ok(())
+}
+
+fn logout() -> CommandResult {
+    delete_auth_token(current_environment())?;
+    ui::success("Signed out of Yaak");
+    Ok(())
+}
+
+async fn whoami() -> CommandResult {
+    let environment = current_environment();
+    let token = match get_auth_token(environment)? {
+        Some(token) => token,
+        None => {
+            ui::warning("Not logged in");
+            ui::info("Please run `yaak auth login`");
+            return Ok(());
+        }
+    };
+
+    let url = format!("{}/api/v1/whoami", environment.api_base_url());
+    let response = http::build_client(Some(&token))?
+        .get(url)
+        .send()
+        .await
+        .map_err(|e| format!("Failed to call whoami endpoint: {e}"))?;
+
+    let status = response.status();
+    let body =
+        response.text().await.map_err(|e| format!("Failed to read whoami response body: {e}"))?;
+
+    if !status.is_success() {
+        if status.as_u16() == 401 {
+            let _ = delete_auth_token(environment);
+            return Err(
+                "Unauthorized to access CLI. Run `yaak auth login` to refresh credentials."
+                    .to_string(),
+            );
+        }
+        return Err(http::parse_api_error(status.as_u16(), &body));
+    }
+
+    println!("{body}");
+    Ok(())
+}
+
+fn current_environment() -> Environment {
+    let value = std::env::var("ENVIRONMENT").ok();
+    parse_environment(value.as_deref())
+}
+
+fn parse_environment(value: Option<&str>) -> Environment {
+    match value {
+        Some("staging") => Environment::Staging,
+        Some("development") => Environment::Development,
+        _ => Environment::Production,
+    }
+}
+
+fn build_oauth_flow(environment: Environment, callback_port: u16) -> CommandResult<OAuthFlow> {
+    let code_verifier = random_hex(32);
+    let state = random_hex(24);
+    let redirect_url = format!("http://127.0.0.1:{callback_port}/oauth/callback");
+
+    let code_challenge = base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .encode(Sha256::digest(code_verifier.as_bytes()));
+
+    let mut auth_url = Url::parse(&format!("{}/login/oauth/authorize", environment.app_base_url()))
+        .map_err(|e| format!("Failed to build OAuth authorize URL: {e}"))?;
+    auth_url
+        .query_pairs_mut()
+        .append_pair("response_type", "code")
+        .append_pair("client_id", OAUTH_CLIENT_ID)
+        .append_pair("redirect_uri", &redirect_url)
+        .append_pair("state", &state)
+        .append_pair("code_challenge_method", "S256")
+        .append_pair("code_challenge", &code_challenge);
+
+    Ok(OAuthFlow {
+        app_base_url: environment.app_base_url().to_string(),
+        auth_url,
+        token_url: format!("{}/login/oauth/access_token", environment.app_base_url()),
+        redirect_url,
+        state,
+        code_verifier,
+    })
+}
+
+async fn receive_oauth_code(
+    listener: TcpListener,
+    expected_state: &str,
+    app_base_url: &str,
+) -> CommandResult<String> {
+    // Browsers speculatively open extra connections that may never carry a
+    // request. Handle each connection concurrently so an idle socket can't
+    // block the one carrying the real callback.
+    let (tx, mut rx) = tokio::sync::mpsc::channel::<CommandResult<String>>(1);
+
+    loop {
+        tokio::select! {
+            accepted = listener.accept() => {
+                let (stream, _) = accepted
+                    .map_err(|e| format!("OAuth callback server accept error: {e}"))?;
+                tokio::spawn(handle_callback_connection(
+                    stream,
+                    expected_state.to_string(),
+                    app_base_url.to_string(),
+                    tx.clone(),
+                ));
+            }
+            result = rx.recv() => {
+                if let Some(result) = result {
+                    return result;
+                }
+            }
+        }
+    }
+}
+
+async fn handle_callback_connection(
+    mut stream: TcpStream,
+    expected_state: String,
+    app_base_url: String,
+    tx: tokio::sync::mpsc::Sender<CommandResult<String>>,
+) {
+    let parsed = match tokio::time::timeout(
+        CALLBACK_READ_TIMEOUT,
+        parse_callback_request(&mut stream),
+    )
+    .await
+    {
+        Ok(parsed) => parsed,
+        Err(_) => return, // Idle speculative connection; drop it
+    };
+
+    match parsed {
+        Ok((state, code)) => {
+            if state != expected_state {
+                let _ = write_bad_request(&mut stream, "Invalid OAuth state").await;
+                return;
+            }
+
+            let success_redirect = format!("{app_base_url}/login/oauth/success");
+            let result = match write_redirect(&mut stream, &success_redirect).await {
+                Ok(()) => Ok(code),
+                Err(e) => Err(format!("Failed responding to OAuth callback: {e}")),
+            };
+            let _ = tx.send(result).await;
+        }
+        Err(error) => {
+            let _ = write_bad_request(&mut stream, &error).await;
+            if error.starts_with("OAuth provider returned error:") {
+                let _ = tx.send(Err(error)).await;
+            }
+        }
+    }
+}
+
+async fn parse_callback_request(stream: &mut TcpStream) -> CommandResult<(String, String)> {
+    let target = read_http_target(stream).await?;
+    if !target.starts_with("/oauth/callback") {
+        return Err("Expected /oauth/callback path".to_string());
+    }
+
+    let url = Url::parse(&format!("http://127.0.0.1{target}"))
+        .map_err(|e| format!("Failed to parse callback URL: {e}"))?;
+    let mut state: Option<String> = None;
+    let mut code: Option<String> = None;
+    let mut oauth_error: Option<String> = None;
+    let mut oauth_error_description: Option<String> = None;
+
+    for (k, v) in url.query_pairs() {
+        if k == "state" {
+            state = Some(v.into_owned());
+        } else if k == "code" {
+            code = Some(v.into_owned());
+        } else if k == "error" {
+            oauth_error = Some(v.into_owned());
+        } else if k == "error_description" {
+            oauth_error_description = Some(v.into_owned());
+        }
+    }
+
+    if let Some(error) = oauth_error {
+        let mut message = format!("OAuth provider returned error: {error}");
+        if let Some(description) = oauth_error_description.filter(|d| !d.is_empty()) {
+            message.push_str(&format!(" ({description})"));
+        }
+        return Err(message);
+    }
+
+    let state = state.ok_or_else(|| "Missing 'state' query parameter".to_string())?;
+    let code = code.ok_or_else(|| "Missing 'code' query parameter".to_string())?;
+
+    if code.is_empty() {
+        return Err("Missing 'code' query parameter".to_string());
+    }
+
+    Ok((state, code))
+}
+
+async fn read_http_target(stream: &mut TcpStream) -> CommandResult<String> {
+    let mut buf = vec![0_u8; MAX_REQUEST_BYTES];
+    let mut total_read = 0_usize;
+
+    loop {
+        let n = stream
+            .read(&mut buf[total_read..])
+            .await
+            .map_err(|e| format!("Failed reading callback request: {e}"))?;
+        if n == 0 {
+            break;
+        }
+        total_read += n;
+
+        if buf[..total_read].windows(4).any(|w| w == b"\r\n\r\n") {
+            break;
+        }
+
+        if total_read == MAX_REQUEST_BYTES {
+            return Err("OAuth callback request too large".to_string());
+        }
+    }
+
+    let req = String::from_utf8_lossy(&buf[..total_read]);
+    let request_line =
+        req.lines().next().ok_or_else(|| "Invalid callback request line".to_string())?;
+    let mut parts = request_line.split_whitespace();
+    let method = parts.next().unwrap_or_default();
+    let target = parts.next().unwrap_or_default();
+
+    if method != "GET" {
+        return Err(format!("Expected GET callback request, got '{method}'"));
+    }
+    if target.is_empty() {
+        return Err("Missing callback request target".to_string());
+    }
+
+    Ok(target.to_string())
+}
+
+async fn write_bad_request(stream: &mut TcpStream, message: &str) -> std::io::Result<()> {
+    let body = format!("Failed to authenticate: {message}");
+    let response = format!(
+        "HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+        body.len(),
+        body
+    );
+    stream.write_all(response.as_bytes()).await?;
+    stream.shutdown().await
+}
+
+async fn write_redirect(stream: &mut TcpStream, location: &str) -> std::io::Result<()> {
+    let response = format!(
+        "HTTP/1.1 302 Found\r\nLocation: {location}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+    );
+    stream.write_all(response.as_bytes()).await?;
+    stream.shutdown().await
+}
+
+async fn exchange_access_token(oauth: &OAuthFlow, code: &str) -> CommandResult<String> {
+    let response = http::build_client(None)?
+        .post(&oauth.token_url)
+        .form(&[
+            ("grant_type", "authorization_code"),
+            ("client_id", OAUTH_CLIENT_ID),
+            ("code", code),
+            ("redirect_uri", oauth.redirect_url.as_str()),
+            ("code_verifier", oauth.code_verifier.as_str()),
+        ])
+        .send()
+        .await
+        .map_err(|e| format!("Failed to exchange OAuth code for access token: {e}"))?;
+
+    let status = response.status();
+    let body =
+        response.text().await.map_err(|e| format!("Failed to read token response body: {e}"))?;
+
+    if !status.is_success() {
+        return Err(format!(
+            "Failed to fetch access token: status={} body={}",
+            status.as_u16(),
+            body
+        ));
+    }
+
+    let parsed: Value =
+        serde_json::from_str(&body).map_err(|e| format!("Invalid token response JSON: {e}"))?;
+    let token = parsed
+        .get("access_token")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| format!("Token response missing access_token: {body}"))?;
+
+    Ok(token.to_string())
+}
+
+fn keyring_entry(environment: Environment) -> CommandResult<Entry> {
+    Entry::new(environment.keyring_service(), KEYRING_USER)
+        .map_err(|e| format!("Failed to initialize auth keyring entry: {e}"))
+}
+
+fn get_auth_token(environment: Environment) -> CommandResult<Option<String>> {
+    let entry = keyring_entry(environment)?;
+    match entry.get_password() {
+        Ok(token) => Ok(Some(token)),
+        Err(keyring::Error::NoEntry) => Ok(None),
+        Err(err) => Err(format!("Failed to read auth token: {err}")),
+    }
+}
+
+fn store_auth_token(environment: Environment, token: &str) -> CommandResult {
+    let entry = keyring_entry(environment)?;
+    entry.set_password(token).map_err(|e| format!("Failed to store auth token: {e}"))
+}
+
+fn delete_auth_token(environment: Environment) -> CommandResult {
+    let entry = keyring_entry(environment)?;
+    match entry.delete_credential() {
+        Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
+        Err(err) => Err(format!("Failed to delete auth token: {err}")),
+    }
+}
+
+fn random_hex(bytes: usize) -> String {
+    let mut data = vec![0_u8; bytes];
+    OsRng.fill_bytes(&mut data);
+    hex::encode(data)
+}
+
+fn confirm_open_browser() -> CommandResult<bool> {
+    if !io::stdin().is_terminal() {
+        return Ok(true);
+    }
+
+    loop {
+        print!("Open default browser? [Y/n]: ");
+        io::stdout().flush().map_err(|e| format!("Failed to flush stdout: {e}"))?;
+
+        let mut input = String::new();
+        io::stdin().read_line(&mut input).map_err(|e| format!("Failed to read input: {e}"))?;
+
+        match input.trim().to_ascii_lowercase().as_str() {
+            "" | "y" | "yes" => return Ok(true),
+            "n" | "no" => return Ok(false),
+            _ => ui::warning("Please answer y or n"),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn environment_mapping() {
+        assert_eq!(parse_environment(Some("staging")), Environment::Staging);
+        assert_eq!(parse_environment(Some("development")), Environment::Development);
+        assert_eq!(parse_environment(Some("production")), Environment::Production);
+        assert_eq!(parse_environment(None), Environment::Production);
+    }
+
+    #[tokio::test]
+    async fn parses_callback_request() {
+        let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind");
+        let addr = listener.local_addr().expect("local addr");
+
+        let server = tokio::spawn(async move {
+            let (mut stream, _) = listener.accept().await.expect("accept");
+            parse_callback_request(&mut stream).await
+        });
+
+        let mut client = TcpStream::connect(addr).await.expect("connect");
+        client
+            .write_all(
+                b"GET /oauth/callback?code=abc123&state=xyz HTTP/1.1\r\nHost: localhost\r\n\r\n",
+            )
+            .await
+            .expect("write");
+
+        let parsed = server.await.expect("join").expect("parse");
+        assert_eq!(parsed.0, "xyz");
+        assert_eq!(parsed.1, "abc123");
+    }
+
+    #[tokio::test]
+    async fn parse_callback_request_oauth_error() {
+        let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind");
+        let addr = listener.local_addr().expect("local addr");
+
+        let server = tokio::spawn(async move {
+            let (mut stream, _) = listener.accept().await.expect("accept");
+            parse_callback_request(&mut stream).await
+        });
+
+        let mut client = TcpStream::connect(addr).await.expect("connect");
+        client
+            .write_all(
+                b"GET /oauth/callback?error=access_denied&error_description=User%20denied&state=xyz HTTP/1.1\r\nHost: localhost\r\n\r\n",
+            )
+            .await
+            .expect("write");
+
+        let err = server.await.expect("join").expect_err("should fail");
+        assert!(err.contains("OAuth provider returned error: access_denied"));
+        assert!(err.contains("User denied"));
+    }
+
+    #[tokio::test]
+    async fn receive_oauth_code_ignores_idle_speculative_connections() {
+        let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind");
+        let addr = listener.local_addr().expect("local addr");
+
+        let server = tokio::spawn(async move {
+            receive_oauth_code(listener, "expected-state", "http://localhost:9444").await
+        });
+
+        // Browsers preconnect sockets that never carry a request; these must
+        // not block the connection carrying the real callback.
+        let _idle1 = TcpStream::connect(addr).await.expect("connect idle 1");
+        let _idle2 = TcpStream::connect(addr).await.expect("connect idle 2");
+        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+
+        let mut client = TcpStream::connect(addr).await.expect("connect");
+        client
+            .write_all(
+                b"GET /oauth/callback?code=abc123&state=expected-state HTTP/1.1\r\nHost: localhost\r\n\r\n",
+            )
+            .await
+            .expect("write");
+
+        let code = tokio::time::timeout(std::time::Duration::from_secs(2), server)
+            .await
+            .expect("idle connections must not block the real callback")
+            .expect("join")
+            .expect("should return code");
+        assert_eq!(code, "abc123");
+    }
+
+    #[tokio::test]
+    async fn receive_oauth_code_fails_fast_on_provider_error() {
+        let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind");
+        let addr = listener.local_addr().expect("local addr");
+
+        let server = tokio::spawn(async move {
+            receive_oauth_code(listener, "expected-state", "http://localhost:9444").await
+        });
+
+        let mut client = TcpStream::connect(addr).await.expect("connect");
+        client
+            .write_all(
+                b"GET /oauth/callback?error=access_denied&state=expected-state HTTP/1.1\r\nHost: localhost\r\n\r\n",
+            )
+            .await
+            .expect("write");
+
+        let result = tokio::time::timeout(std::time::Duration::from_secs(2), server)
+            .await
+            .expect("should not timeout")
+            .expect("join");
+        let err = result.expect_err("should return oauth error");
+        assert!(err.contains("OAuth provider returned error: access_denied"));
+    }
+
+    #[test]
+    fn builds_oauth_flow_with_pkce() {
+        let flow = build_oauth_flow(Environment::Development, 8080).expect("flow");
+        assert!(flow.auth_url.as_str().contains("code_challenge_method=S256"));
+        assert!(
+            flow.auth_url
+                .as_str()
+                .contains("redirect_uri=http%3A%2F%2F127.0.0.1%3A8080%2Foauth%2Fcallback")
+        );
+        assert_eq!(flow.redirect_url, "http://127.0.0.1:8080/oauth/callback");
+        assert_eq!(flow.token_url, "http://localhost:9444/login/oauth/access_token");
+    }
+}

crates-cli/yaak-cli/src/commands/cookie_jar.rs

@@ -0,0 +1,42 @@
+use crate::cli::{CookieJarArgs, CookieJarCommands};
+use crate::context::CliContext;
+use crate::utils::workspace::resolve_workspace_id;
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+pub fn run(ctx: &CliContext, args: CookieJarArgs) -> i32 {
+    let result = match args.command {
+        CookieJarCommands::List { workspace_id } => list(ctx, workspace_id.as_deref()),
+    };
+
+    match result {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+fn list(ctx: &CliContext, workspace_id: Option<&str>) -> CommandResult {
+    let workspace_id = resolve_workspace_id(ctx, workspace_id, "cookie-jar list")?;
+    let cookie_jars = ctx
+        .db()
+        .list_cookie_jars(&workspace_id)
+        .map_err(|e| format!("Failed to list cookie jars: {e}"))?;
+
+    if cookie_jars.is_empty() {
+        println!("No cookie jars found in workspace {}", workspace_id);
+    } else {
+        for cookie_jar in cookie_jars {
+            println!(
+                "{} - {} ({} cookies)",
+                cookie_jar.id,
+                cookie_jar.name,
+                cookie_jar.cookies.len()
+            );
+        }
+    }
+
+    Ok(())
+}

crates-cli/yaak-cli/src/commands/environment.rs

@@ -0,0 +1,179 @@
+use crate::cli::{EnvironmentArgs, EnvironmentCommands};
+use crate::context::CliContext;
+use crate::utils::confirm::confirm_delete;
+use crate::utils::json::{
+    apply_merge_patch, is_json_shorthand, merge_workspace_id_arg, parse_optional_json,
+    parse_required_json, require_id, validate_create_id,
+};
+use crate::utils::schema::append_agent_hints;
+use crate::utils::workspace::resolve_workspace_id;
+use schemars::schema_for;
+use yaak_models::models::Environment;
+use yaak_models::util::UpdateSource;
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+pub fn run(ctx: &CliContext, args: EnvironmentArgs) -> i32 {
+    let result = match args.command {
+        EnvironmentCommands::List { workspace_id } => list(ctx, workspace_id.as_deref()),
+        EnvironmentCommands::Schema { pretty } => schema(pretty),
+        EnvironmentCommands::Show { environment_id } => show(ctx, &environment_id),
+        EnvironmentCommands::Create { workspace_id, name, json } => {
+            create(ctx, workspace_id, name, json)
+        }
+        EnvironmentCommands::Update { json, json_input } => update(ctx, json, json_input),
+        EnvironmentCommands::Delete { environment_id, yes } => delete(ctx, &environment_id, yes),
+    };
+
+    match result {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+fn schema(pretty: bool) -> CommandResult {
+    let mut schema = serde_json::to_value(schema_for!(Environment))
+        .map_err(|e| format!("Failed to serialize environment schema: {e}"))?;
+    append_agent_hints(&mut schema);
+
+    let output =
+        if pretty { serde_json::to_string_pretty(&schema) } else { serde_json::to_string(&schema) }
+            .map_err(|e| format!("Failed to format environment schema JSON: {e}"))?;
+    println!("{output}");
+    Ok(())
+}
+
+fn list(ctx: &CliContext, workspace_id: Option<&str>) -> CommandResult {
+    let workspace_id = resolve_workspace_id(ctx, workspace_id, "environment list")?;
+    let environments = ctx
+        .query_manager()
+        .with_tx(|tx| {
+            tx.ensure_base_environment(&workspace_id)?;
+            tx.list_environments(&workspace_id)
+        })
+        .map_err(|e| format!("Failed to list environments: {e}"))?;
+
+    if environments.is_empty() {
+        println!("No environments found in workspace {}", workspace_id);
+    } else {
+        for environment in environments {
+            println!("{} - {} ({})", environment.id, environment.name, environment.parent_model);
+        }
+    }
+    Ok(())
+}
+
+fn show(ctx: &CliContext, environment_id: &str) -> CommandResult {
+    let environment = ctx
+        .db()
+        .get_environment(environment_id)
+        .map_err(|e| format!("Failed to get environment: {e}"))?;
+    let output = serde_json::to_string_pretty(&environment)
+        .map_err(|e| format!("Failed to serialize environment: {e}"))?;
+    println!("{output}");
+    Ok(())
+}
+
+fn create(
+    ctx: &CliContext,
+    workspace_id: Option<String>,
+    name: Option<String>,
+    json: Option<String>,
+) -> CommandResult {
+    let json_shorthand =
+        workspace_id.as_deref().filter(|v| is_json_shorthand(v)).map(str::to_owned);
+    let workspace_id_arg = workspace_id.filter(|v| !is_json_shorthand(v));
+
+    let payload = parse_optional_json(json, json_shorthand, "environment create")?;
+
+    if let Some(payload) = payload {
+        if name.is_some() {
+            return Err("environment create cannot combine --name with JSON payload".to_string());
+        }
+
+        validate_create_id(&payload, "environment")?;
+        let mut environment: Environment = serde_json::from_value(payload)
+            .map_err(|e| format!("Failed to parse environment create JSON: {e}"))?;
+        let fallback_workspace_id =
+            if workspace_id_arg.is_none() && environment.workspace_id.is_empty() {
+                Some(resolve_workspace_id(ctx, None, "environment create")?)
+            } else {
+                None
+            };
+        merge_workspace_id_arg(
+            workspace_id_arg.as_deref().or(fallback_workspace_id.as_deref()),
+            &mut environment.workspace_id,
+            "environment create",
+        )?;
+
+        if environment.parent_model.is_empty() {
+            environment.parent_model = "environment".to_string();
+        }
+
+        let created = ctx
+            .query_manager()
+            .with_tx(|tx| tx.upsert_environment(&environment, &UpdateSource::Sync))
+            .map_err(|e| format!("Failed to create environment: {e}"))?;
+
+        println!("Created environment: {}", created.id);
+        return Ok(());
+    }
+
+    let workspace_id =
+        resolve_workspace_id(ctx, workspace_id_arg.as_deref(), "environment create")?;
+    let name = name.ok_or_else(|| {
+        "environment create requires --name unless JSON payload is provided".to_string()
+    })?;
+
+    let environment = Environment {
+        workspace_id,
+        name,
+        parent_model: "environment".to_string(),
+        ..Default::default()
+    };
+
+    let created = ctx
+        .query_manager()
+        .with_tx(|tx| tx.upsert_environment(&environment, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to create environment: {e}"))?;
+
+    println!("Created environment: {}", created.id);
+    Ok(())
+}
+
+fn update(ctx: &CliContext, json: Option<String>, json_input: Option<String>) -> CommandResult {
+    let patch = parse_required_json(json, json_input, "environment update")?;
+    let id = require_id(&patch, "environment update")?;
+
+    let existing = ctx
+        .db()
+        .get_environment(&id)
+        .map_err(|e| format!("Failed to get environment for update: {e}"))?;
+    let updated = apply_merge_patch(&existing, &patch, &id, "environment update")?;
+
+    let saved = ctx
+        .query_manager()
+        .with_tx(|tx| tx.upsert_environment(&updated, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to update environment: {e}"))?;
+
+    println!("Updated environment: {}", saved.id);
+    Ok(())
+}
+
+fn delete(ctx: &CliContext, environment_id: &str, yes: bool) -> CommandResult {
+    if !yes && !confirm_delete("environment", environment_id) {
+        println!("Aborted");
+        return Ok(());
+    }
+
+    let deleted = ctx
+        .query_manager()
+        .with_tx(|tx| tx.delete_environment_by_id(environment_id, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to delete environment: {e}"))?;
+
+    println!("Deleted environment: {}", deleted.id);
+    Ok(())
+}

crates-cli/yaak-cli/src/commands/folder.rs

@@ -0,0 +1,159 @@
+use crate::cli::{FolderArgs, FolderCommands};
+use crate::context::CliContext;
+use crate::utils::confirm::confirm_delete;
+use crate::utils::json::{
+    apply_merge_patch, is_json_shorthand, merge_workspace_id_arg, parse_optional_json,
+    parse_required_json, require_id, validate_create_id,
+};
+use crate::utils::schema::append_agent_hints;
+use crate::utils::workspace::resolve_workspace_id;
+use schemars::schema_for;
+use yaak_models::models::Folder;
+use yaak_models::util::UpdateSource;
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+pub fn run(ctx: &CliContext, args: FolderArgs) -> i32 {
+    let result = match args.command {
+        FolderCommands::List { workspace_id } => list(ctx, workspace_id.as_deref()),
+        FolderCommands::Schema { pretty } => schema(pretty),
+        FolderCommands::Show { folder_id } => show(ctx, &folder_id),
+        FolderCommands::Create { workspace_id, name, json } => {
+            create(ctx, workspace_id, name, json)
+        }
+        FolderCommands::Update { json, json_input } => update(ctx, json, json_input),
+        FolderCommands::Delete { folder_id, yes } => delete(ctx, &folder_id, yes),
+    };
+
+    match result {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+fn schema(pretty: bool) -> CommandResult {
+    let mut schema = serde_json::to_value(schema_for!(Folder))
+        .map_err(|e| format!("Failed to serialize folder schema: {e}"))?;
+    append_agent_hints(&mut schema);
+
+    let output =
+        if pretty { serde_json::to_string_pretty(&schema) } else { serde_json::to_string(&schema) }
+            .map_err(|e| format!("Failed to format folder schema JSON: {e}"))?;
+    println!("{output}");
+    Ok(())
+}
+
+fn list(ctx: &CliContext, workspace_id: Option<&str>) -> CommandResult {
+    let workspace_id = resolve_workspace_id(ctx, workspace_id, "folder list")?;
+    let folders =
+        ctx.db().list_folders(&workspace_id).map_err(|e| format!("Failed to list folders: {e}"))?;
+    if folders.is_empty() {
+        println!("No folders found in workspace {}", workspace_id);
+    } else {
+        for folder in folders {
+            println!("{} - {}", folder.id, folder.name);
+        }
+    }
+    Ok(())
+}
+
+fn show(ctx: &CliContext, folder_id: &str) -> CommandResult {
+    let folder =
+        ctx.db().get_folder(folder_id).map_err(|e| format!("Failed to get folder: {e}"))?;
+    let output = serde_json::to_string_pretty(&folder)
+        .map_err(|e| format!("Failed to serialize folder: {e}"))?;
+    println!("{output}");
+    Ok(())
+}
+
+fn create(
+    ctx: &CliContext,
+    workspace_id: Option<String>,
+    name: Option<String>,
+    json: Option<String>,
+) -> CommandResult {
+    let json_shorthand =
+        workspace_id.as_deref().filter(|v| is_json_shorthand(v)).map(str::to_owned);
+    let workspace_id_arg = workspace_id.filter(|v| !is_json_shorthand(v));
+
+    let payload = parse_optional_json(json, json_shorthand, "folder create")?;
+
+    if let Some(payload) = payload {
+        if name.is_some() {
+            return Err("folder create cannot combine --name with JSON payload".to_string());
+        }
+
+        validate_create_id(&payload, "folder")?;
+        let mut folder: Folder = serde_json::from_value(payload)
+            .map_err(|e| format!("Failed to parse folder create JSON: {e}"))?;
+        let fallback_workspace_id = if workspace_id_arg.is_none() && folder.workspace_id.is_empty()
+        {
+            Some(resolve_workspace_id(ctx, None, "folder create")?)
+        } else {
+            None
+        };
+        merge_workspace_id_arg(
+            workspace_id_arg.as_deref().or(fallback_workspace_id.as_deref()),
+            &mut folder.workspace_id,
+            "folder create",
+        )?;
+
+        let created = ctx
+            .query_manager()
+            .with_tx(|tx| tx.upsert_folder(&folder, &UpdateSource::Sync))
+            .map_err(|e| format!("Failed to create folder: {e}"))?;
+
+        println!("Created folder: {}", created.id);
+        return Ok(());
+    }
+
+    let workspace_id = resolve_workspace_id(ctx, workspace_id_arg.as_deref(), "folder create")?;
+    let name = name.ok_or_else(|| {
+        "folder create requires --name unless JSON payload is provided".to_string()
+    })?;
+
+    let folder = Folder { workspace_id, name, ..Default::default() };
+
+    let created = ctx
+        .query_manager()
+        .with_tx(|tx| tx.upsert_folder(&folder, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to create folder: {e}"))?;
+
+    println!("Created folder: {}", created.id);
+    Ok(())
+}
+
+fn update(ctx: &CliContext, json: Option<String>, json_input: Option<String>) -> CommandResult {
+    let patch = parse_required_json(json, json_input, "folder update")?;
+    let id = require_id(&patch, "folder update")?;
+
+    let existing =
+        ctx.db().get_folder(&id).map_err(|e| format!("Failed to get folder for update: {e}"))?;
+    let updated = apply_merge_patch(&existing, &patch, &id, "folder update")?;
+
+    let saved = ctx
+        .query_manager()
+        .with_tx(|tx| tx.upsert_folder(&updated, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to update folder: {e}"))?;
+
+    println!("Updated folder: {}", saved.id);
+    Ok(())
+}
+
+fn delete(ctx: &CliContext, folder_id: &str, yes: bool) -> CommandResult {
+    if !yes && !confirm_delete("folder", folder_id) {
+        println!("Aborted");
+        return Ok(());
+    }
+
+    let deleted = ctx
+        .query_manager()
+        .with_tx(|tx| tx.delete_folder_by_id(folder_id, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to delete folder: {e}"))?;
+
+    println!("Deleted folder: {}", deleted.id);
+    Ok(())
+}

crates-cli/yaak-cli/src/commands/import_export.rs

@@ -0,0 +1,277 @@
+use crate::cli::{ExportArgs, ImportArgs};
+use crate::context::CliContext;
+use crate::utils::workspace::resolve_workspace_id;
+use std::fs;
+use std::io::ErrorKind;
+use yaak_models::export::{self, ExportDataParams};
+use yaak::import;
+use yaak_models::util::{
+    BatchUpsertResult, ImportDestination, ImportOrigin, ImportPlanAction, ImportPlanItem,
+};
+use yaak_plugins::events::{ImportResources, PluginContext};
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+pub async fn run_import(ctx: &CliContext, args: ImportArgs) -> i32 {
+    match import(ctx, args).await {
+        Ok((result, items)) => {
+            println!("Imported {}", format_counts(&result));
+            if let Some(skipped) = format_skipped(&items) {
+                println!("Skipped {skipped}");
+            }
+            0
+        }
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+pub fn run_export(ctx: &CliContext, args: ExportArgs) -> i32 {
+    match export(ctx, args) {
+        Ok(count) => {
+            println!("Exported {count} workspace(s)");
+            0
+        }
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+async fn import(
+    ctx: &CliContext,
+    args: ImportArgs,
+) -> CommandResult<(BatchUpsertResult, Vec<ImportPlanItem>)> {
+    if let Some(workspace_id) = args.workspace_id.as_deref() {
+        ctx.db()
+            .get_workspace(workspace_id)
+            .map_err(|e| format!("Failed to get workspace '{workspace_id}': {e}"))?;
+    }
+
+    let file_contents = read_import_file(&args.file)?;
+    let plugin_context = PluginContext::new(None, args.workspace_id.clone());
+    let plugin_manager = ctx.plugin_manager();
+    let import_result = plugin_manager
+        .import_data(&plugin_context, &file_contents)
+        .await
+        .map_err(|e| format!("Failed to import data: {e}"))?;
+    let importer = import_result.importer;
+    let resources = import_result.resources;
+    let workspace_id = args.workspace_id;
+    if workspace_id.is_none() && resources_need_current_workspace(&resources) {
+        return Err(
+            "This import requires a workspace context. Provide --workspace-id <WORKSPACE_ID>."
+                .to_string(),
+        );
+    }
+    let destination = match workspace_id {
+        Some(workspace_id) => {
+            ImportDestination::ExistingWorkspace { workspace_id, folder_id: None }
+        }
+        None => ImportDestination::NewWorkspace,
+    };
+    let plan = import::plan_import_resources(
+        ctx.query_manager(),
+        importer,
+        destination,
+        resources,
+        import_result.source_keys,
+        Some(file_origin(&args.file)),
+    )
+    .map_err(|e| format!("Failed to plan import: {e}"))?;
+    let items = plan.items.clone();
+    let imported = import::commit_import_plan(ctx.query_manager(), plan)
+        .map_err(|e| format!("Failed to import data: {e}"))?;
+    Ok((imported, items))
+}
+
+fn file_origin(path: &std::path::Path) -> ImportOrigin {
+    let canonical = fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
+    let label = canonical
+        .file_name()
+        .map(|name| name.to_string_lossy().to_string())
+        .unwrap_or_else(|| path.display().to_string());
+    ImportOrigin { origin: canonical.to_string_lossy().to_string(), label }
+}
+
+/// Summarize what the default selection left untouched during a merging re-import.
+fn format_skipped(items: &[ImportPlanItem]) -> Option<String> {
+    let count = |action: ImportPlanAction| items.iter().filter(|i| i.action == action).count();
+    let plural = |n: usize| if n == 1 { "" } else { "s" };
+
+    let mut parts = Vec::new();
+    let deletions = count(ImportPlanAction::Delete);
+    if deletions > 0 {
+        parts.push(format!("{deletions} removed from source (not deleted locally)"));
+    }
+    let conflicts = count(ImportPlanAction::Conflict);
+    if conflicts > 0 {
+        parts.push(format!("{conflicts} conflict{} (kept local changes)", plural(conflicts)));
+    }
+    let keep_local = count(ImportPlanAction::KeepLocal);
+    if keep_local > 0 {
+        parts.push(format!("{keep_local} with local edits"));
+    }
+    let ignored = count(ImportPlanAction::Ignored);
+    if ignored > 0 {
+        parts.push(format!("{ignored} ignored"));
+    }
+    let unchanged = count(ImportPlanAction::Unchanged);
+    if unchanged > 0 {
+        parts.push(format!("{unchanged} unchanged"));
+    }
+
+    if parts.is_empty() { None } else { Some(parts.join(", ")) }
+}
+
+/// Write a file so that afterwards it is either the old one or the whole new one.
+///
+/// Writing in place would truncate the previous export before the new one existed, so an
+/// interrupted run loses both. Instead the bytes go to a neighbouring file, are flushed, and
+/// take the target's name in one step. The directory is flushed too: `sync_all` on a file
+/// promises its contents, not that the name it just gained will survive a power cut.
+fn write_durably(path: &std::path::Path, bytes: &[u8]) -> std::io::Result<()> {
+    use std::io::Write;
+
+    let dir = match path.parent() {
+        Some(p) if !p.as_os_str().is_empty() => p,
+        _ => std::path::Path::new("."),
+    };
+    // Alongside the target, because a rename is only atomic within one filesystem.
+    let mut name = path.file_name().unwrap_or_default().to_os_string();
+    name.push(format!(".tmp{}", std::process::id()));
+    let tmp = dir.join(name);
+
+    let write = |tmp: &std::path::Path| -> std::io::Result<()> {
+        let mut file = std::fs::File::create(tmp)?;
+        file.write_all(bytes)?;
+        file.sync_all()
+    };
+    if let Err(e) = write(&tmp) {
+        let _ = std::fs::remove_file(&tmp);
+        return Err(e);
+    }
+    if let Err(e) = std::fs::rename(&tmp, path) {
+        let _ = std::fs::remove_file(&tmp);
+        return Err(e);
+    }
+
+    // Only Unix lets a directory be opened for this. Elsewhere the rename is as much as
+    // the platform offers, and the file itself is already flushed.
+    #[cfg(unix)]
+    std::fs::File::open(dir)?.sync_all()?;
+
+    Ok(())
+}
+
+fn export(ctx: &CliContext, args: ExportArgs) -> CommandResult<usize> {
+    let workspace_ids = resolve_export_workspace_ids(ctx, args.workspace_ids, args.all)?;
+    let workspace_id_refs: Vec<&str> = workspace_ids.iter().map(String::as_str).collect();
+    let document = export::export_data(ExportDataParams {
+        query_manager: ctx.query_manager(),
+        yaak_version: env!("CARGO_PKG_VERSION"),
+        workspace_ids: workspace_id_refs,
+        include_private_environments: args.include_private_environments,
+    })
+    .map_err(|e| format!("Failed to export data: {e}"))?;
+    // Flushed before reporting success: an export is a backup, and a backup that the
+    // command called done while it was still only in the page cache is the one case
+    // where saying nothing went wrong is worst.
+    write_durably(&args.file, document.as_bytes())
+        .map_err(|e| format!("Failed to write {}: {e}", args.file.display()))?;
+
+    Ok(workspace_ids.len())
+}
+
+fn resolve_export_workspace_ids(
+    ctx: &CliContext,
+    workspace_ids: Vec<String>,
+    all: bool,
+) -> CommandResult<Vec<String>> {
+    if all {
+        let workspaces =
+            ctx.db().list_workspaces().map_err(|e| format!("Failed to list workspaces: {e}"))?;
+        if workspaces.is_empty() {
+            return Err("No workspaces found to export".to_string());
+        }
+        return Ok(workspaces.into_iter().map(|w| w.id).collect());
+    }
+
+    if workspace_ids.is_empty() {
+        return resolve_workspace_id(ctx, None, "export").map(|id| vec![id]);
+    }
+
+    for workspace_id in &workspace_ids {
+        ctx.db()
+            .get_workspace(workspace_id)
+            .map_err(|e| format!("Failed to get workspace '{workspace_id}': {e}"))?;
+    }
+    Ok(workspace_ids)
+}
+
+fn read_import_file(path: &std::path::Path) -> CommandResult<String> {
+    fs::read_to_string(path).map_err(|err| {
+        if err.kind() == ErrorKind::InvalidData {
+            format!(
+                "Import file must be UTF-8 text; binary files are not supported: {}",
+                path.display()
+            )
+        } else {
+            format!("Unable to read import file {}: {err}", path.display())
+        }
+    })
+}
+
+fn resources_need_current_workspace(resources: &ImportResources) -> bool {
+    resources.workspaces.iter().any(|w| w.id == "CURRENT_WORKSPACE")
+        || resources.environments.iter().any(|e| {
+            e.workspace_id == "CURRENT_WORKSPACE"
+                || e.parent_id.as_deref() == Some("CURRENT_WORKSPACE")
+        })
+        || resources.folders.iter().any(|f| {
+            f.workspace_id == "CURRENT_WORKSPACE"
+                || f.folder_id.as_deref() == Some("CURRENT_WORKSPACE")
+        })
+        || resources.http_requests.iter().any(|r| {
+            r.workspace_id == "CURRENT_WORKSPACE"
+                || r.folder_id.as_deref() == Some("CURRENT_WORKSPACE")
+        })
+        || resources.grpc_requests.iter().any(|r| {
+            r.workspace_id == "CURRENT_WORKSPACE"
+                || r.folder_id.as_deref() == Some("CURRENT_WORKSPACE")
+        })
+        || resources.websocket_requests.iter().any(|r| {
+            r.workspace_id == "CURRENT_WORKSPACE"
+                || r.folder_id.as_deref() == Some("CURRENT_WORKSPACE")
+        })
+}
+
+fn format_counts(result: &BatchUpsertResult) -> String {
+    let names = [
+        "workspace",
+        "environment",
+        "folder",
+        "HTTP request",
+        "gRPC request",
+        "WebSocket request",
+    ];
+    let counts = [
+        (result.workspaces.len(), names[0]),
+        (result.environments.len(), names[1]),
+        (result.folders.len(), names[2]),
+        (result.http_requests.len(), names[3]),
+        (result.grpc_requests.len(), names[4]),
+        (result.websocket_requests.len(), names[5]),
+    ];
+
+    let non_zero: Vec<String> = counts
+        .into_iter()
+        .filter(|(count, _)| *count > 0)
+        .map(|(count, name)| format!("{count} {name}{}", if count == 1 { "" } else { "s" }))
+        .collect();
+
+    if non_zero.is_empty() { "nothing".to_string() } else { non_zero.join(", ") }
+}

crates-cli/yaak-cli/src/commands/mod.rs

@@ -0,0 +1,12 @@
+pub mod agent;
+pub mod auth;
+pub mod cookie_jar;
+pub mod environment;
+pub mod folder;
+pub mod import_export;
+pub mod plugin;
+pub mod request;
+pub mod response;
+pub mod send;
+pub mod template_function;
+pub mod workspace;

crates-cli/yaak-cli/src/commands/request.rs

@@ -0,0 +1,620 @@
+use crate::cli::{RequestArgs, RequestCommands, RequestSchemaType};
+use crate::context::CliContext;
+use crate::utils::confirm::confirm_delete;
+use crate::utils::json::{
+    apply_merge_patch, is_json_shorthand, merge_workspace_id_arg, parse_optional_json,
+    parse_required_json, require_id, validate_create_id,
+};
+use crate::utils::schema::append_agent_hints;
+use crate::utils::workspace::resolve_workspace_id;
+use schemars::schema_for;
+use serde_json::{Map, Value, json};
+use std::collections::HashMap;
+use std::io::Write;
+use tokio::sync::mpsc;
+use yaak::send::{SendHttpRequestByIdWithPluginsParams, send_http_request_by_id_with_plugins};
+use yaak_http::sender::HttpResponseEvent as SenderHttpResponseEvent;
+use yaak_models::models::{GrpcRequest, HttpRequest, WebsocketRequest};
+use yaak_models::queries::any_request::AnyRequest;
+use yaak_models::util::UpdateSource;
+use yaak_plugins::events::{FormInput, FormInputBase, JsonPrimitive, PluginContext};
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+pub async fn run(
+    ctx: &CliContext,
+    args: RequestArgs,
+    environment: Option<&str>,
+    cookie_jar_id: Option<&str>,
+    verbose: bool,
+) -> i32 {
+    let result = match args.command {
+        RequestCommands::List { workspace_id } => list(ctx, workspace_id.as_deref()),
+        RequestCommands::Show { request_id } => show(ctx, &request_id),
+        RequestCommands::Send { request_id } => {
+            return match send_request_by_id(ctx, &request_id, environment, cookie_jar_id, verbose)
+                .await
+            {
+                Ok(()) => 0,
+                Err(error) => {
+                    eprintln!("Error: {error}");
+                    1
+                }
+            };
+        }
+        RequestCommands::Schema { request_type, pretty } => {
+            return match schema(ctx, request_type, pretty).await {
+                Ok(()) => 0,
+                Err(error) => {
+                    eprintln!("Error: {error}");
+                    1
+                }
+            };
+        }
+        RequestCommands::Create { workspace_id, name, method, url, json } => {
+            create(ctx, workspace_id, name, method, url, json)
+        }
+        RequestCommands::Update { json, json_input } => update(ctx, json, json_input),
+        RequestCommands::Delete { request_id, yes } => delete(ctx, &request_id, yes),
+    };
+
+    match result {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+fn list(ctx: &CliContext, workspace_id: Option<&str>) -> CommandResult {
+    let workspace_id = resolve_workspace_id(ctx, workspace_id, "request list")?;
+    let requests = ctx
+        .db()
+        .list_http_requests(&workspace_id)
+        .map_err(|e| format!("Failed to list requests: {e}"))?;
+    if requests.is_empty() {
+        println!("No requests found in workspace {}", workspace_id);
+    } else {
+        for request in requests {
+            println!("{} - {} {}", request.id, request.method, request.name);
+        }
+    }
+    Ok(())
+}
+
+async fn schema(ctx: &CliContext, request_type: RequestSchemaType, pretty: bool) -> CommandResult {
+    let mut schema = match request_type {
+        RequestSchemaType::Http => serde_json::to_value(schema_for!(HttpRequest))
+            .map_err(|e| format!("Failed to serialize HTTP request schema: {e}"))?,
+        RequestSchemaType::Grpc => serde_json::to_value(schema_for!(GrpcRequest))
+            .map_err(|e| format!("Failed to serialize gRPC request schema: {e}"))?,
+        RequestSchemaType::Websocket => serde_json::to_value(schema_for!(WebsocketRequest))
+            .map_err(|e| format!("Failed to serialize WebSocket request schema: {e}"))?,
+    };
+
+    enrich_schema_guidance(&mut schema, request_type);
+    append_agent_hints(&mut schema);
+
+    if let Err(error) = merge_auth_schema_from_plugins(ctx, &mut schema).await {
+        eprintln!("Warning: Failed to enrich authentication schema from plugins: {error}");
+    }
+
+    let output =
+        if pretty { serde_json::to_string_pretty(&schema) } else { serde_json::to_string(&schema) }
+            .map_err(|e| format!("Failed to format schema JSON: {e}"))?;
+    println!("{output}");
+    Ok(())
+}
+
+/// `request create` only builds HTTP requests, but `request schema` will happily hand
+/// out gRPC and WebSocket schemas. Without this, a gRPC payload deserializes into an
+/// HttpRequest with its unknown fields dropped, quietly producing a broken request
+/// (the gRPC method name lands in `method`, and `service` disappears).
+fn reject_non_http_payload(payload: &Value, context: &str) -> CommandResult {
+    let Some(object) = payload.as_object() else {
+        return Ok(());
+    };
+
+    if let Some(model) = object.get("model").and_then(Value::as_str)
+        && !model.is_empty()
+        && model != "http_request"
+    {
+        return Err(format!(
+            "{context} only supports HTTP requests, but the payload has \"model\": \"{model}\". The CLI cannot work with {model} requests yet; use the Yaak app instead."
+        ));
+    }
+
+    let known: std::collections::BTreeSet<String> = serde_json::to_value(schema_for!(HttpRequest))
+        .ok()
+        .and_then(|schema| schema.get("properties").and_then(Value::as_object).cloned())
+        .map(|properties| properties.keys().cloned().collect())
+        .unwrap_or_default();
+
+    if known.is_empty() {
+        return Ok(());
+    }
+
+    let unknown: Vec<&str> =
+        object.keys().filter(|key| !known.contains(*key)).map(String::as_str).collect();
+
+    if !unknown.is_empty() {
+        return Err(format!(
+            "{context} got fields that are not part of an HTTP request: {}. If this is a gRPC or WebSocket request, the CLI cannot work with it yet. Run `yaak request schema http` for the valid fields.",
+            unknown.join(", ")
+        ));
+    }
+
+    Ok(())
+}
+
+fn enrich_schema_guidance(schema: &mut Value, request_type: RequestSchemaType) {
+    if !matches!(request_type, RequestSchemaType::Http) {
+        return;
+    }
+
+    let Some(properties) = schema.get_mut("properties").and_then(Value::as_object_mut) else {
+        return;
+    };
+
+    if let Some(url_schema) = properties.get_mut("url").and_then(Value::as_object_mut) {
+        append_description(
+            url_schema,
+            "For path segments like `/foo/:id/comments/:commentId`, put concrete values in `urlParameters` using names that keep the leading `:` (for example `:id`, `:commentId`). A name without the `:` is sent as a query string parameter instead, leaving the placeholder in the path.",
+        );
+    }
+
+    if let Some(body_type_schema) = properties.get_mut("bodyType").and_then(Value::as_object_mut) {
+        append_description(
+            body_type_schema,
+            "Known values: `application/json`, `text/xml`, `application/x-www-form-urlencoded`, `multipart/form-data`, `graphql`, `binary`, `other`, or null for no body. This selects how `body` is encoded; it does NOT add a `Content-Type` header. Add that header yourself, matching the body type (`other` pairs with `text/plain` and `graphql` with `application/json`). Multipart is the exception: its header is generated at send time to carry the boundary.",
+        );
+    }
+
+    if let Some(body_schema) = properties.get_mut("body").and_then(Value::as_object_mut) {
+        append_description(
+            body_schema,
+            "Shape depends on `bodyType`. Text-ish types (`application/json`, `text/xml`, `other`) use `{\"text\": \"...\"}` where the value is a string, so JSON bodies are a JSON string containing JSON. Form types use `{\"form\": [{\"name\": \"a\", \"value\": \"1\", \"enabled\": true}]}`, and a multipart entry may use `file` (an absolute path) and `contentType` instead of `value`. `binary` uses `{\"filePath\": \"/abs/path\"}`. `graphql` uses `{\"query\": \"...\", \"variables\": \"{}\", \"operationName\": \"\"}` where `variables` is a string of JSON.",
+        );
+    }
+}
+
+fn append_description(schema: &mut Map<String, Value>, extra: &str) {
+    match schema.get_mut("description") {
+        Some(Value::String(existing)) if !existing.trim().is_empty() => {
+            if !existing.ends_with(' ') {
+                existing.push(' ');
+            }
+            existing.push_str(extra);
+        }
+        _ => {
+            schema.insert("description".to_string(), Value::String(extra.to_string()));
+        }
+    }
+}
+
+async fn merge_auth_schema_from_plugins(
+    ctx: &CliContext,
+    schema: &mut Value,
+) -> Result<(), String> {
+    let plugin_context = PluginContext::new_empty();
+    let plugin_manager = ctx.plugin_manager();
+    let summaries = plugin_manager
+        .get_http_authentication_summaries(&plugin_context)
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let mut auth_variants = Vec::new();
+    for (_, summary) in summaries {
+        let config = match plugin_manager
+            .get_http_authentication_config(
+                &plugin_context,
+                &summary.name,
+                HashMap::<String, JsonPrimitive>::new(),
+                "yaakcli_request_schema",
+            )
+            .await
+        {
+            Ok(config) => config,
+            Err(error) => {
+                eprintln!(
+                    "Warning: Failed to load auth config for strategy '{}': {}",
+                    summary.name, error
+                );
+                continue;
+            }
+        };
+
+        auth_variants.push(auth_variant_schema(&summary.name, &summary.label, &config.args));
+    }
+
+    let Some(properties) = schema.get_mut("properties").and_then(Value::as_object_mut) else {
+        return Ok(());
+    };
+
+    let Some(auth_schema) = properties.get_mut("authentication") else {
+        return Ok(());
+    };
+
+    if !auth_variants.is_empty() {
+        let mut one_of = vec![auth_schema.clone()];
+        one_of.extend(auth_variants);
+        *auth_schema = json!({ "oneOf": one_of });
+    }
+
+    Ok(())
+}
+
+fn auth_variant_schema(auth_name: &str, auth_label: &str, args: &[FormInput]) -> Value {
+    let mut properties = Map::new();
+    let mut required = Vec::new();
+    for input in args {
+        add_input_schema(input, &mut properties, &mut required);
+    }
+
+    let mut schema = json!({
+        "title": auth_label,
+        "description": format!("Authentication values for strategy '{}'", auth_name),
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": true
+    });
+
+    if !required.is_empty() {
+        schema["required"] = json!(required);
+    }
+
+    schema
+}
+
+fn add_input_schema(
+    input: &FormInput,
+    properties: &mut Map<String, Value>,
+    required: &mut Vec<String>,
+) {
+    match input {
+        FormInput::Text(v) => add_base_schema(
+            &v.base,
+            json!({
+                "type": "string",
+                "writeOnly": v.password.unwrap_or(false),
+            }),
+            properties,
+            required,
+        ),
+        FormInput::Editor(v) => add_base_schema(
+            &v.base,
+            json!({
+                "type": "string",
+                "x-editorLanguage": v.language.clone(),
+            }),
+            properties,
+            required,
+        ),
+        FormInput::Select(v) => {
+            let options: Vec<Value> =
+                v.options.iter().map(|o| Value::String(o.value.clone())).collect();
+            add_base_schema(
+                &v.base,
+                json!({
+                    "type": "string",
+                    "enum": options,
+                }),
+                properties,
+                required,
+            );
+        }
+        FormInput::Checkbox(v) => {
+            add_base_schema(&v.base, json!({ "type": "boolean" }), properties, required);
+        }
+        FormInput::File(v) => {
+            if v.multiple.unwrap_or(false) {
+                add_base_schema(
+                    &v.base,
+                    json!({
+                        "type": "array",
+                        "items": { "type": "string" },
+                    }),
+                    properties,
+                    required,
+                );
+            } else {
+                add_base_schema(&v.base, json!({ "type": "string" }), properties, required);
+            }
+        }
+        FormInput::HttpRequest(v) => {
+            add_base_schema(&v.base, json!({ "type": "string" }), properties, required);
+        }
+        FormInput::KeyValue(v) => {
+            add_base_schema(
+                &v.base,
+                json!({
+                    "type": "object",
+                    "additionalProperties": true,
+                }),
+                properties,
+                required,
+            );
+        }
+        FormInput::Accordion(v) => {
+            if let Some(children) = &v.inputs {
+                for child in children {
+                    add_input_schema(child, properties, required);
+                }
+            }
+        }
+        FormInput::HStack(v) => {
+            if let Some(children) = &v.inputs {
+                for child in children {
+                    add_input_schema(child, properties, required);
+                }
+            }
+        }
+        FormInput::Banner(v) => {
+            if let Some(children) = &v.inputs {
+                for child in children {
+                    add_input_schema(child, properties, required);
+                }
+            }
+        }
+        FormInput::Markdown(_) => {}
+    }
+}
+
+fn add_base_schema(
+    base: &FormInputBase,
+    mut schema: Value,
+    properties: &mut Map<String, Value>,
+    required: &mut Vec<String>,
+) {
+    if base.hidden.unwrap_or(false) || base.name.trim().is_empty() {
+        return;
+    }
+
+    if let Some(description) = &base.description {
+        schema["description"] = Value::String(description.clone());
+    }
+    if let Some(label) = &base.label {
+        schema["title"] = Value::String(label.clone());
+    }
+    if let Some(default_value) = &base.default_value {
+        schema["default"] = Value::String(default_value.clone());
+    }
+
+    let name = base.name.clone();
+    properties.insert(name.clone(), schema);
+    if !base.optional.unwrap_or(false) {
+        required.push(name);
+    }
+}
+
+fn create(
+    ctx: &CliContext,
+    workspace_id: Option<String>,
+    name: Option<String>,
+    method: Option<String>,
+    url: Option<String>,
+    json: Option<String>,
+) -> CommandResult {
+    let json_shorthand =
+        workspace_id.as_deref().filter(|v| is_json_shorthand(v)).map(str::to_owned);
+    let workspace_id_arg = workspace_id.filter(|v| !is_json_shorthand(v));
+
+    let payload = parse_optional_json(json, json_shorthand, "request create")?;
+
+    if let Some(payload) = payload {
+        if name.is_some() || method.is_some() || url.is_some() {
+            return Err("request create cannot combine simple flags with JSON payload".to_string());
+        }
+
+        validate_create_id(&payload, "request")?;
+        reject_non_http_payload(&payload, "request create")?;
+        let mut request: HttpRequest = serde_json::from_value(payload)
+            .map_err(|e| format!("Failed to parse request create JSON: {e}"))?;
+        let fallback_workspace_id = if workspace_id_arg.is_none() && request.workspace_id.is_empty()
+        {
+            Some(resolve_workspace_id(ctx, None, "request create")?)
+        } else {
+            None
+        };
+        merge_workspace_id_arg(
+            workspace_id_arg.as_deref().or(fallback_workspace_id.as_deref()),
+            &mut request.workspace_id,
+            "request create",
+        )?;
+
+        let created = ctx
+            .query_manager()
+            .with_tx(|tx| tx.upsert_http_request(&request, &UpdateSource::Sync))
+            .map_err(|e| format!("Failed to create request: {e}"))?;
+
+        println!("Created request: {}", created.id);
+        return Ok(());
+    }
+
+    let workspace_id = resolve_workspace_id(ctx, workspace_id_arg.as_deref(), "request create")?;
+    let name = name.unwrap_or_default();
+    let url = url.unwrap_or_default();
+    let mut request = HttpRequest { workspace_id, name, url, ..Default::default() };
+    // Only override the method when one was given; `HttpRequest::default()` is the
+    // single place the fallback ("GET") is defined.
+    if let Some(method) = method {
+        request.method = method.to_uppercase();
+    }
+
+    let created = ctx
+        .query_manager()
+        .with_tx(|tx| tx.upsert_http_request(&request, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to create request: {e}"))?;
+
+    println!("Created request: {}", created.id);
+    Ok(())
+}
+
+fn update(ctx: &CliContext, json: Option<String>, json_input: Option<String>) -> CommandResult {
+    let patch = parse_required_json(json, json_input, "request update")?;
+    let id = require_id(&patch, "request update")?;
+    reject_non_http_payload(&patch, "request update")?;
+
+    let existing = ctx
+        .db()
+        .get_http_request(&id)
+        .map_err(|e| format!("Failed to get request for update: {e}"))?;
+    let updated = apply_merge_patch(&existing, &patch, &id, "request update")?;
+
+    let saved = ctx
+        .query_manager()
+        .with_tx(|tx| tx.upsert_http_request(&updated, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to update request: {e}"))?;
+
+    println!("Updated request: {}", saved.id);
+    Ok(())
+}
+
+fn show(ctx: &CliContext, request_id: &str) -> CommandResult {
+    let request =
+        ctx.db().get_http_request(request_id).map_err(|e| format!("Failed to get request: {e}"))?;
+    let output = serde_json::to_string_pretty(&request)
+        .map_err(|e| format!("Failed to serialize request: {e}"))?;
+    println!("{output}");
+    Ok(())
+}
+
+fn delete(ctx: &CliContext, request_id: &str, yes: bool) -> CommandResult {
+    if !yes && !confirm_delete("request", request_id) {
+        println!("Aborted");
+        return Ok(());
+    }
+
+    let deleted = ctx
+        .query_manager()
+        .with_tx(|tx| tx.delete_http_request_by_id(request_id, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to delete request: {e}"))?;
+    println!("Deleted request: {}", deleted.id);
+    Ok(())
+}
+
+/// Send a request by ID and print response in the same format as legacy `send`.
+pub async fn send_request_by_id(
+    ctx: &CliContext,
+    request_id: &str,
+    environment: Option<&str>,
+    cookie_jar_id: Option<&str>,
+    verbose: bool,
+) -> Result<(), String> {
+    let request =
+        ctx.db().get_any_request(request_id).map_err(|e| format!("Failed to get request: {e}"))?;
+    match request {
+        AnyRequest::HttpRequest(http_request) => {
+            send_http_request_by_id(
+                ctx,
+                &http_request.id,
+                &http_request.workspace_id,
+                environment,
+                cookie_jar_id,
+                verbose,
+            )
+            .await
+        }
+        AnyRequest::GrpcRequest(_) => {
+            Err("gRPC request send is not implemented yet in yaak-cli".to_string())
+        }
+        AnyRequest::WebsocketRequest(_) => {
+            Err("WebSocket request send is not implemented yet in yaak-cli".to_string())
+        }
+    }
+}
+
+async fn send_http_request_by_id(
+    ctx: &CliContext,
+    request_id: &str,
+    workspace_id: &str,
+    environment: Option<&str>,
+    cookie_jar_id: Option<&str>,
+    verbose: bool,
+) -> Result<(), String> {
+    let cookie_jar_id = resolve_cookie_jar_id(ctx, workspace_id, cookie_jar_id)?;
+
+    let plugin_context =
+        PluginContext::new(Some("cli".to_string()), Some(workspace_id.to_string()));
+
+    let (event_tx, mut event_rx) = mpsc::channel::<SenderHttpResponseEvent>(100);
+    let (body_chunk_tx, mut body_chunk_rx) = mpsc::unbounded_channel::<Vec<u8>>();
+    let event_handle = tokio::spawn(async move {
+        while let Some(event) = event_rx.recv().await {
+            if verbose && !matches!(event, SenderHttpResponseEvent::ChunkReceived { .. }) {
+                println!("{}", event);
+            }
+        }
+    });
+    // Verbose mode has a second writer on stdout (the event task above), and the two
+    // race: the body could land in the middle of the headers, or run onto the same
+    // line as the status. So buffer the body while verbose and write it once the
+    // events are done. Without -v nothing else writes, so stream it straight through.
+    let body_handle = tokio::task::spawn_blocking(move || {
+        let mut buffered = Vec::new();
+        let mut stdout = std::io::stdout();
+        while let Some(chunk) = body_chunk_rx.blocking_recv() {
+            if verbose {
+                buffered.extend_from_slice(&chunk);
+                continue;
+            }
+            if stdout.write_all(&chunk).is_err() {
+                break;
+            }
+            let _ = stdout.flush();
+        }
+        buffered
+    });
+    let response_dir = ctx.data_dir().join("responses");
+
+    let result = send_http_request_by_id_with_plugins(SendHttpRequestByIdWithPluginsParams {
+        query_manager: ctx.query_manager(),
+        blob_manager: ctx.blob_manager(),
+        request_id,
+        environment_id: environment,
+        update_source: UpdateSource::Sync,
+        cookie_jar_id,
+        response_dir: &response_dir,
+        emit_events_to: Some(event_tx),
+        emit_response_body_chunks_to: Some(body_chunk_tx),
+        plugin_manager: ctx.plugin_manager(),
+        encryption_manager: ctx.encryption_manager.clone(),
+        plugin_context: &plugin_context,
+        cancelled_rx: None,
+        connection_manager: ctx.connection_manager(),
+    })
+    .await;
+
+    // Await the events first so every `*`, `>`, and `<` line is out before the body.
+    let _ = event_handle.await;
+    if let Ok(buffered) = body_handle.await
+        && !buffered.is_empty()
+    {
+        let mut stdout = std::io::stdout();
+        let _ = stdout.write_all(&buffered);
+        let _ = stdout.flush();
+    }
+
+    result.map_err(|e| e.to_string())?;
+    Ok(())
+}
+
+pub(crate) fn resolve_cookie_jar_id(
+    ctx: &CliContext,
+    workspace_id: &str,
+    explicit_cookie_jar_id: Option<&str>,
+) -> Result<Option<String>, String> {
+    if let Some(cookie_jar_id) = explicit_cookie_jar_id {
+        return Ok(Some(cookie_jar_id.to_string()));
+    }
+
+    let default_cookie_jar = ctx
+        .db()
+        .list_cookie_jars(workspace_id)
+        .map_err(|e| format!("Failed to list cookie jars: {e}"))?
+        .into_iter()
+        .min_by_key(|jar| jar.created_at)
+        .map(|jar| jar.id);
+    Ok(default_cookie_jar)
+}

crates-cli/yaak-cli/src/commands/response.rs

@@ -0,0 +1,141 @@
+use crate::cli::{ResponseArgs, ResponseCommands};
+use crate::context::CliContext;
+use crate::utils::confirm::confirm_delete;
+use crate::utils::workspace::resolve_workspace_id;
+use std::io::Write;
+use yaak_models::models::HttpResponse;
+use yaak_models::util::UpdateSource;
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+pub fn run(ctx: &CliContext, args: ResponseArgs) -> i32 {
+    let result = match args.command {
+        ResponseCommands::List { id, limit } => list(ctx, id.as_deref(), limit),
+        ResponseCommands::Show { id } => show(ctx, &id),
+        ResponseCommands::Body { id } => body(ctx, &id),
+        ResponseCommands::Delete { id, yes } => delete(ctx, &id, yes),
+    };
+
+    match result {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+/// Accepts a response ID, or a request ID meaning "the latest response for that request".
+fn resolve_response(ctx: &CliContext, id: &str) -> CommandResult<HttpResponse> {
+    if let Ok(response) = ctx.db().get_http_response(id) {
+        return Ok(response);
+    }
+
+    if ctx.db().get_http_request(id).is_ok() {
+        return ctx
+            .db()
+            .list_http_responses_for_request(id, Some(1))
+            .map_err(|e| format!("Failed to list responses: {e}"))?
+            .into_iter()
+            .next()
+            .ok_or_else(|| format!("Request {id} has no stored responses yet"));
+    }
+
+    Err(format!("Could not resolve ID '{id}' as a response or request"))
+}
+
+fn list(ctx: &CliContext, id: Option<&str>, limit: Option<u64>) -> CommandResult {
+    // An explicit request ID scopes to that request; anything else lists the workspace.
+    let responses = match id {
+        Some(id) if ctx.db().get_http_request(id).is_ok() => ctx
+            .db()
+            .list_http_responses_for_request(id, limit)
+            .map_err(|e| format!("Failed to list responses: {e}"))?,
+        other => {
+            let workspace_id = resolve_workspace_id(ctx, other, "response list")?;
+            ctx.db()
+                .list_http_responses(&workspace_id, limit)
+                .map_err(|e| format!("Failed to list responses: {e}"))?
+        }
+    };
+
+    if responses.is_empty() {
+        println!("No responses found");
+        return Ok(());
+    }
+
+    for response in responses {
+        let status = match response.error {
+            // Errors can be a paragraph of nested debug output; `show` has the full text.
+            Some(error) => {
+                let first_line = error.lines().next().unwrap_or_default();
+                let summary = match first_line.char_indices().nth(80) {
+                    Some((cut, _)) => format!("{}...", &first_line[..cut]),
+                    None => first_line.to_string(),
+                };
+                format!("ERROR {summary}")
+            }
+            None => {
+                let reason = response.status_reason.unwrap_or_default();
+                format!("{} {}", response.status, reason).trim_end().to_string()
+            }
+        };
+        println!("{} - {} {} ({}ms)", response.id, status, response.url, response.elapsed);
+    }
+
+    Ok(())
+}
+
+fn show(ctx: &CliContext, id: &str) -> CommandResult {
+    let response = resolve_response(ctx, id)?;
+    let output = serde_json::to_string_pretty(&response)
+        .map_err(|e| format!("Failed to serialize response: {e}"))?;
+    println!("{output}");
+    Ok(())
+}
+
+fn body(ctx: &CliContext, id: &str) -> CommandResult {
+    let response = resolve_response(ctx, id)?;
+    let Some(body_path) = response.body_path else {
+        return Err(format!("Response {} has no stored body", response.id));
+    };
+
+    let bytes = std::fs::read(&body_path)
+        .map_err(|e| format!("Failed to read response body at {body_path}: {e}"))?;
+
+    let mut stdout = std::io::stdout();
+    stdout.write_all(&bytes).map_err(|e| format!("Failed to write response body: {e}"))?;
+    stdout.flush().map_err(|e| format!("Failed to flush response body: {e}"))?;
+    Ok(())
+}
+
+fn delete(ctx: &CliContext, id: &str, yes: bool) -> CommandResult {
+    // Deleting is scoped to a whole request or workspace, since a single stored
+    // response is rarely the thing someone wants to remove.
+    if ctx.db().get_http_request(id).is_ok() {
+        if !yes && !confirm_delete("responses for request", id) {
+            println!("Aborted");
+            return Ok(());
+        }
+        let count = ctx
+            .query_manager()
+            .with_tx(|tx| tx.delete_all_http_responses_for_request(id, &UpdateSource::Sync))
+            .map_err(|e| format!("Failed to delete responses: {e}"))?;
+        println!("Deleted {count} responses for request {id}");
+        return Ok(());
+    }
+
+    let workspace_id = resolve_workspace_id(ctx, Some(id), "response delete")?;
+    if !yes && !confirm_delete("responses for workspace", &workspace_id) {
+        println!("Aborted");
+        return Ok(());
+    }
+    let count = ctx
+        .query_manager()
+        .with_tx(|tx| {
+            tx.delete_all_http_responses_for_workspace(&workspace_id, &UpdateSource::Sync)
+        })
+        .map_err(|e| format!("Failed to delete responses: {e}"))?;
+    println!("Deleted {count} responses for workspace {workspace_id}");
+    Ok(())
+}

crates-cli/yaak-cli/src/commands/send.rs

@@ -0,0 +1,242 @@
+use crate::cli::SendArgs;
+use crate::commands::request;
+use crate::context::CliContext;
+use futures::future::join_all;
+use yaak_models::queries::any_request::AnyRequest;
+
+enum ExecutionMode {
+    Sequential,
+    Parallel,
+}
+
+pub async fn run(
+    ctx: &CliContext,
+    args: SendArgs,
+    environment: Option<&str>,
+    cookie_jar_id: Option<&str>,
+    verbose: bool,
+) -> i32 {
+    match send_target(ctx, args, environment, cookie_jar_id, verbose).await {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+async fn send_target(
+    ctx: &CliContext,
+    args: SendArgs,
+    environment: Option<&str>,
+    cookie_jar_id: Option<&str>,
+    verbose: bool,
+) -> Result<(), String> {
+    let mode = if args.parallel { ExecutionMode::Parallel } else { ExecutionMode::Sequential };
+
+    if let Ok(request) = ctx.db().get_any_request(&args.id) {
+        let workspace_id = match &request {
+            AnyRequest::HttpRequest(r) => r.workspace_id.clone(),
+            AnyRequest::GrpcRequest(r) => r.workspace_id.clone(),
+            AnyRequest::WebsocketRequest(r) => r.workspace_id.clone(),
+        };
+        let resolved_cookie_jar_id =
+            request::resolve_cookie_jar_id(ctx, &workspace_id, cookie_jar_id)?;
+
+        return request::send_request_by_id(
+            ctx,
+            &args.id,
+            environment,
+            resolved_cookie_jar_id.as_deref(),
+            verbose,
+        )
+        .await;
+    }
+
+    if let Ok(folder) = ctx.db().get_folder(&args.id) {
+        let resolved_cookie_jar_id =
+            request::resolve_cookie_jar_id(ctx, &folder.workspace_id, cookie_jar_id)?;
+
+        let request_ids = collect_folder_request_ids(ctx, &args.id)?;
+        if request_ids.is_empty() {
+            println!("No requests found in folder {}", args.id);
+            return Ok(());
+        }
+        return send_many(
+            ctx,
+            request_ids,
+            mode,
+            args.fail_fast,
+            environment,
+            resolved_cookie_jar_id.as_deref(),
+            verbose,
+        )
+        .await;
+    }
+
+    if let Ok(workspace) = ctx.db().get_workspace(&args.id) {
+        let resolved_cookie_jar_id =
+            request::resolve_cookie_jar_id(ctx, &workspace.id, cookie_jar_id)?;
+
+        let request_ids = collect_workspace_request_ids(ctx, &args.id)?;
+        if request_ids.is_empty() {
+            println!("No requests found in workspace {}", args.id);
+            return Ok(());
+        }
+        return send_many(
+            ctx,
+            request_ids,
+            mode,
+            args.fail_fast,
+            environment,
+            resolved_cookie_jar_id.as_deref(),
+            verbose,
+        )
+        .await;
+    }
+
+    Err(format!("Could not resolve ID '{}' as request, folder, or workspace", args.id))
+}
+
+fn collect_folder_request_ids(ctx: &CliContext, folder_id: &str) -> Result<Vec<String>, String> {
+    let mut ids = Vec::new();
+
+    let mut http_ids = ctx
+        .db()
+        .list_http_requests_for_folder_recursive(folder_id)
+        .map_err(|e| format!("Failed to list HTTP requests in folder: {e}"))?
+        .into_iter()
+        .map(|r| r.id)
+        .collect::<Vec<_>>();
+    ids.append(&mut http_ids);
+
+    let mut grpc_ids = ctx
+        .db()
+        .list_grpc_requests_for_folder_recursive(folder_id)
+        .map_err(|e| format!("Failed to list gRPC requests in folder: {e}"))?
+        .into_iter()
+        .map(|r| r.id)
+        .collect::<Vec<_>>();
+    ids.append(&mut grpc_ids);
+
+    let mut websocket_ids = ctx
+        .db()
+        .list_websocket_requests_for_folder_recursive(folder_id)
+        .map_err(|e| format!("Failed to list WebSocket requests in folder: {e}"))?
+        .into_iter()
+        .map(|r| r.id)
+        .collect::<Vec<_>>();
+    ids.append(&mut websocket_ids);
+
+    Ok(ids)
+}
+
+fn collect_workspace_request_ids(
+    ctx: &CliContext,
+    workspace_id: &str,
+) -> Result<Vec<String>, String> {
+    let mut ids = Vec::new();
+
+    let mut http_ids = ctx
+        .db()
+        .list_http_requests(workspace_id)
+        .map_err(|e| format!("Failed to list HTTP requests in workspace: {e}"))?
+        .into_iter()
+        .map(|r| r.id)
+        .collect::<Vec<_>>();
+    ids.append(&mut http_ids);
+
+    let mut grpc_ids = ctx
+        .db()
+        .list_grpc_requests(workspace_id)
+        .map_err(|e| format!("Failed to list gRPC requests in workspace: {e}"))?
+        .into_iter()
+        .map(|r| r.id)
+        .collect::<Vec<_>>();
+    ids.append(&mut grpc_ids);
+
+    let mut websocket_ids = ctx
+        .db()
+        .list_websocket_requests(workspace_id)
+        .map_err(|e| format!("Failed to list WebSocket requests in workspace: {e}"))?
+        .into_iter()
+        .map(|r| r.id)
+        .collect::<Vec<_>>();
+    ids.append(&mut websocket_ids);
+
+    Ok(ids)
+}
+
+async fn send_many(
+    ctx: &CliContext,
+    request_ids: Vec<String>,
+    mode: ExecutionMode,
+    fail_fast: bool,
+    environment: Option<&str>,
+    cookie_jar_id: Option<&str>,
+    verbose: bool,
+) -> Result<(), String> {
+    let mut success_count = 0usize;
+    let mut failures: Vec<(String, String)> = Vec::new();
+
+    match mode {
+        ExecutionMode::Sequential => {
+            for request_id in request_ids {
+                match request::send_request_by_id(
+                    ctx,
+                    &request_id,
+                    environment,
+                    cookie_jar_id,
+                    verbose,
+                )
+                .await
+                {
+                    Ok(()) => success_count += 1,
+                    Err(error) => {
+                        failures.push((request_id, error));
+                        if fail_fast {
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        ExecutionMode::Parallel => {
+            let tasks = request_ids
+                .iter()
+                .map(|request_id| async move {
+                    (
+                        request_id.clone(),
+                        request::send_request_by_id(
+                            ctx,
+                            request_id,
+                            environment,
+                            cookie_jar_id,
+                            verbose,
+                        )
+                        .await,
+                    )
+                })
+                .collect::<Vec<_>>();
+
+            for (request_id, result) in join_all(tasks).await {
+                match result {
+                    Ok(()) => success_count += 1,
+                    Err(error) => failures.push((request_id, error)),
+                }
+            }
+        }
+    }
+
+    let failure_count = failures.len();
+    println!("Send summary: {success_count} succeeded, {failure_count} failed");
+
+    if failure_count == 0 {
+        return Ok(());
+    }
+
+    for (request_id, error) in failures {
+        eprintln!("  {}: {}", request_id, error);
+    }
+    Err("One or more requests failed".to_string())
+}

crates-cli/yaak-cli/src/commands/template_function.rs

@@ -0,0 +1,111 @@
+use crate::cli::{TemplateFunctionArgs, TemplateFunctionCommands};
+use crate::context::CliContext;
+use yaak_plugins::events::{PluginContext, TemplateFunction};
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+pub async fn run(ctx: &CliContext, args: TemplateFunctionArgs) -> i32 {
+    let result = match args.command {
+        TemplateFunctionCommands::List { filter } => list(ctx, filter.as_deref()).await,
+        TemplateFunctionCommands::Show { name, pretty } => show(ctx, &name, pretty).await,
+    };
+
+    match result {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+/// Template functions come from plugins, so the only accurate list is the one the
+/// installed plugins report right now.
+async fn all(ctx: &CliContext) -> CommandResult<Vec<TemplateFunction>> {
+    let plugin_context = PluginContext::new_empty();
+    let summaries = ctx
+        .plugin_manager()
+        .get_template_function_summaries(&plugin_context)
+        .await
+        .map_err(|e| format!("Failed to list template functions: {e}"))?;
+
+    let mut functions: Vec<TemplateFunction> =
+        summaries.into_iter().flat_map(|summary| summary.functions).collect();
+    functions.sort_by(|a, b| a.name.cmp(&b.name));
+    Ok(functions)
+}
+
+async fn list(ctx: &CliContext, filter: Option<&str>) -> CommandResult {
+    let mut functions = all(ctx).await?;
+
+    if let Some(filter) = filter {
+        let needle = filter.to_lowercase();
+        functions.retain(|f| f.name.to_lowercase().contains(&needle));
+    }
+
+    if functions.is_empty() {
+        match filter {
+            Some(filter) => println!("No template functions matching '{filter}'"),
+            None => println!("No template functions found"),
+        }
+        return Ok(());
+    }
+
+    for function in functions {
+        let args = function.args.iter().filter_map(arg_name).collect::<Vec<_>>().join(", ");
+        match function.description {
+            Some(description) if !description.is_empty() => {
+                println!("{}({}) - {}", function.name, args, description)
+            }
+            _ => println!("{}({})", function.name, args),
+        }
+    }
+
+    Ok(())
+}
+
+async fn show(ctx: &CliContext, name: &str, pretty: bool) -> CommandResult {
+    let functions = all(ctx).await?;
+    let function = functions
+        .iter()
+        .find(|f| {
+            f.name == name
+                || f.aliases.as_ref().is_some_and(|aliases| aliases.iter().any(|a| a == name))
+        })
+        .ok_or_else(|| {
+            let names = functions.iter().map(|f| f.name.as_str()).collect::<Vec<_>>();
+            format!("No template function named '{name}'. Available: {}", names.join(", "))
+        })?;
+
+    let output = if pretty {
+        serde_json::to_string_pretty(function)
+    } else {
+        serde_json::to_string(function)
+    }
+    .map_err(|e| format!("Failed to serialize template function: {e}"))?;
+
+    println!("{output}");
+    Ok(())
+}
+
+fn arg_name(arg: &yaak_plugins::events::TemplateFunctionArg) -> Option<String> {
+    use yaak_plugins::events::{FormInput, TemplateFunctionArg};
+
+    let TemplateFunctionArg::FormInput(input) = arg;
+    let base = match input {
+        FormInput::Text(v) => &v.base,
+        FormInput::Editor(v) => &v.base,
+        FormInput::Select(v) => &v.base,
+        FormInput::Checkbox(v) => &v.base,
+        FormInput::File(v) => &v.base,
+        FormInput::HttpRequest(v) => &v.base,
+        FormInput::KeyValue(v) => &v.base,
+        // Layout-only inputs have no value of their own
+        FormInput::Accordion(_)
+        | FormInput::HStack(_)
+        | FormInput::Banner(_)
+        | FormInput::Markdown(_) => return None,
+    };
+
+    if base.name.trim().is_empty() { None } else { Some(base.name.clone()) }
+}

crates-cli/yaak-cli/src/commands/workspace.rs

@@ -0,0 +1,140 @@
+use crate::cli::{WorkspaceArgs, WorkspaceCommands};
+use crate::context::CliContext;
+use crate::utils::confirm::confirm_delete;
+use crate::utils::json::{
+    apply_merge_patch, parse_optional_json, parse_required_json, require_id, validate_create_id,
+};
+use crate::utils::schema::append_agent_hints;
+use schemars::schema_for;
+use yaak_models::models::Workspace;
+use yaak_models::util::UpdateSource;
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+pub fn run(ctx: &CliContext, args: WorkspaceArgs) -> i32 {
+    let result = match args.command {
+        WorkspaceCommands::List => list(ctx),
+        WorkspaceCommands::Schema { pretty } => schema(pretty),
+        WorkspaceCommands::Show { workspace_id } => show(ctx, &workspace_id),
+        WorkspaceCommands::Create { name, json, json_input } => create(ctx, name, json, json_input),
+        WorkspaceCommands::Update { json, json_input } => update(ctx, json, json_input),
+        WorkspaceCommands::Delete { workspace_id, yes } => delete(ctx, &workspace_id, yes),
+    };
+
+    match result {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}
+
+fn schema(pretty: bool) -> CommandResult {
+    let mut schema = serde_json::to_value(schema_for!(Workspace))
+        .map_err(|e| format!("Failed to serialize workspace schema: {e}"))?;
+    append_agent_hints(&mut schema);
+
+    let output =
+        if pretty { serde_json::to_string_pretty(&schema) } else { serde_json::to_string(&schema) }
+            .map_err(|e| format!("Failed to format workspace schema JSON: {e}"))?;
+    println!("{output}");
+    Ok(())
+}
+
+fn list(ctx: &CliContext) -> CommandResult {
+    let workspaces =
+        ctx.db().list_workspaces().map_err(|e| format!("Failed to list workspaces: {e}"))?;
+    if workspaces.is_empty() {
+        println!("No workspaces found");
+    } else {
+        for workspace in workspaces {
+            println!("{} - {}", workspace.id, workspace.name);
+        }
+    }
+    Ok(())
+}
+
+fn show(ctx: &CliContext, workspace_id: &str) -> CommandResult {
+    let workspace = ctx
+        .db()
+        .get_workspace(workspace_id)
+        .map_err(|e| format!("Failed to get workspace: {e}"))?;
+    let output = serde_json::to_string_pretty(&workspace)
+        .map_err(|e| format!("Failed to serialize workspace: {e}"))?;
+    println!("{output}");
+    Ok(())
+}
+
+fn create(
+    ctx: &CliContext,
+    name: Option<String>,
+    json: Option<String>,
+    json_input: Option<String>,
+) -> CommandResult {
+    let payload = parse_optional_json(json, json_input, "workspace create")?;
+
+    if let Some(payload) = payload {
+        if name.is_some() {
+            return Err("workspace create cannot combine --name with JSON payload".to_string());
+        }
+
+        validate_create_id(&payload, "workspace")?;
+        let workspace: Workspace = serde_json::from_value(payload)
+            .map_err(|e| format!("Failed to parse workspace create JSON: {e}"))?;
+
+        let created = ctx
+            .query_manager()
+            .with_tx(|tx| tx.upsert_workspace(&workspace, &UpdateSource::Sync))
+            .map_err(|e| format!("Failed to create workspace: {e}"))?;
+        println!("Created workspace: {}", created.id);
+        return Ok(());
+    }
+
+    let name = name.ok_or_else(|| {
+        "workspace create requires --name unless JSON payload is provided".to_string()
+    })?;
+
+    let workspace = Workspace { name, ..Default::default() };
+    let created = ctx
+        .query_manager()
+        .with_tx(|tx| tx.upsert_workspace(&workspace, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to create workspace: {e}"))?;
+    println!("Created workspace: {}", created.id);
+    Ok(())
+}
+
+fn update(ctx: &CliContext, json: Option<String>, json_input: Option<String>) -> CommandResult {
+    let patch = parse_required_json(json, json_input, "workspace update")?;
+    let id = require_id(&patch, "workspace update")?;
+
+    let existing = ctx
+        .db()
+        .get_workspace(&id)
+        .map_err(|e| format!("Failed to get workspace for update: {e}"))?;
+    let updated = apply_merge_patch(&existing, &patch, &id, "workspace update")?;
+
+    let saved = ctx
+        .query_manager()
+        .with_tx(|tx| tx.upsert_workspace(&updated, &UpdateSource::Sync))
+        .map_err(|e| format!("Failed to update workspace: {e}"))?;
+
+    println!("Updated workspace: {}", saved.id);
+    Ok(())
+}
+
+fn delete(ctx: &CliContext, workspace_id: &str, yes: bool) -> CommandResult {
+    if !yes && !confirm_delete("workspace", workspace_id) {
+        println!("Aborted");
+        return Ok(());
+    }
+
+    let deleted = ctx
+        .query_manager()
+        .with_tx(|tx| {
+            tx.delete_workspace_by_id(workspace_id, &UpdateSource::Sync, ctx.blob_manager())
+        })
+        .map_err(|e| format!("Failed to delete workspace: {e}"))?;
+    println!("Deleted workspace: {}", deleted.id);
+    Ok(())
+}

crates-cli/yaak-cli/src/context.rs

@@ -0,0 +1,163 @@
+use crate::plugin_events::CliPluginEventBridge;
+use include_dir::{Dir, include_dir};
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use tokio::sync::Mutex;
+use yaak_crypto::manager::EncryptionManager;
+use yaak_http::manager::HttpConnectionManager;
+use yaak_models::blob_manager::BlobManager;
+use yaak_models::client_db::ClientDb;
+use yaak_models::query_manager::QueryManager;
+use yaak_plugins::events::PluginContext;
+use yaak_plugins::manager::PluginManager;
+
+const EMBEDDED_PLUGIN_RUNTIME: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/../../crates-tauri/yaak-app-client/vendored/plugin-runtime/index.cjs"
+));
+static EMBEDDED_VENDORED_PLUGINS: Dir<'_> =
+    include_dir!("$CARGO_MANIFEST_DIR/../../crates-tauri/yaak-app-client/vendored/plugins");
+
+#[derive(Clone, Debug, Default)]
+pub struct CliExecutionContext {
+    pub request_id: Option<String>,
+    pub workspace_id: Option<String>,
+    pub environment_id: Option<String>,
+    pub cookie_jar_id: Option<String>,
+}
+
+pub struct CliContext {
+    data_dir: PathBuf,
+    query_manager: QueryManager,
+    blob_manager: BlobManager,
+    pub encryption_manager: Arc<EncryptionManager>,
+    connection_manager: Arc<HttpConnectionManager>,
+    plugin_manager: Option<Arc<PluginManager>>,
+    plugin_event_bridge: Mutex<Option<CliPluginEventBridge>>,
+}
+
+impl CliContext {
+    pub fn new(data_dir: PathBuf, app_id: &str) -> Self {
+        let db_path = data_dir.join("db.sqlite");
+        let blob_path = data_dir.join("blobs.sqlite");
+        let (query_manager, blob_manager, _rx) =
+            match yaak_models::init_standalone(&db_path, &blob_path) {
+                Ok(v) => v,
+                Err(err) => {
+                    eprintln!("Error: Failed to initialize database: {err}");
+                    std::process::exit(1);
+                }
+            };
+
+        // Guest: the desktop may have this DB open, so only what's safe beside a live session
+        let _ = query_manager.with_tx(|tx| {
+            yaak_lifecycle::on_launch(&yaak_lifecycle::Host::guest(), tx, &blob_manager)
+        });
+
+        let encryption_manager = Arc::new(EncryptionManager::new(query_manager.clone(), app_id));
+
+        Self {
+            data_dir,
+            query_manager,
+            blob_manager,
+            encryption_manager,
+            connection_manager: Arc::new(HttpConnectionManager::new()),
+            plugin_manager: None,
+            plugin_event_bridge: Mutex::new(None),
+        }
+    }
+
+    pub async fn init_plugins(&mut self, execution_context: CliExecutionContext) {
+        let vendored_plugin_dir = self.data_dir.join("vendored-plugins");
+        let installed_plugin_dir = self.data_dir.join("installed-plugins");
+        let node_bin_path = PathBuf::from("node");
+
+        prepare_embedded_vendored_plugins(&vendored_plugin_dir)
+            .expect("Failed to prepare bundled plugins");
+
+        let plugin_runtime_main =
+            std::env::var("YAAK_PLUGIN_RUNTIME").map(PathBuf::from).unwrap_or_else(|_| {
+                prepare_embedded_plugin_runtime(&self.data_dir)
+                    .expect("Failed to prepare embedded plugin runtime")
+            });
+
+        match PluginManager::new(
+            vendored_plugin_dir,
+            installed_plugin_dir,
+            node_bin_path,
+            plugin_runtime_main,
+            &self.query_manager,
+            &PluginContext::new_empty(),
+            false,
+        )
+        .await
+        {
+            Ok(plugin_manager) => {
+                let plugin_manager = Arc::new(plugin_manager);
+                let plugin_event_bridge = CliPluginEventBridge::start(
+                    plugin_manager.clone(),
+                    self.query_manager.clone(),
+                    self.blob_manager.clone(),
+                    self.encryption_manager.clone(),
+                    self.connection_manager.clone(),
+                    self.data_dir.clone(),
+                    execution_context,
+                )
+                .await;
+                self.plugin_manager = Some(plugin_manager);
+                *self.plugin_event_bridge.lock().await = Some(plugin_event_bridge);
+            }
+            Err(err) => {
+                eprintln!("Warning: Failed to initialize plugins: {err}");
+            }
+        }
+    }
+
+    pub fn data_dir(&self) -> &Path {
+        &self.data_dir
+    }
+
+    pub fn db(&self) -> ClientDb<'_> {
+        self.query_manager.connect()
+    }
+
+    pub fn query_manager(&self) -> &QueryManager {
+        &self.query_manager
+    }
+
+    pub fn blob_manager(&self) -> &BlobManager {
+        &self.blob_manager
+    }
+
+    pub fn connection_manager(&self) -> &HttpConnectionManager {
+        &self.connection_manager
+    }
+
+    pub fn plugin_manager(&self) -> Arc<PluginManager> {
+        self.plugin_manager.clone().expect("Plugin manager was not initialized for this command")
+    }
+
+    pub async fn shutdown(&self) {
+        if let Some(plugin_manager) = &self.plugin_manager {
+            if let Some(plugin_event_bridge) = self.plugin_event_bridge.lock().await.take() {
+                plugin_event_bridge.shutdown(plugin_manager).await;
+            }
+            plugin_manager.terminate().await;
+        }
+    }
+}
+
+fn prepare_embedded_plugin_runtime(data_dir: &Path) -> std::io::Result<PathBuf> {
+    let runtime_dir = data_dir.join("vendored").join("plugin-runtime");
+    fs::create_dir_all(&runtime_dir)?;
+    let runtime_main = runtime_dir.join("index.cjs");
+    fs::write(&runtime_main, EMBEDDED_PLUGIN_RUNTIME)?;
+    Ok(runtime_main)
+}
+
+fn prepare_embedded_vendored_plugins(vendored_plugin_dir: &Path) -> std::io::Result<()> {
+    fs::create_dir_all(vendored_plugin_dir)?;
+    EMBEDDED_VENDORED_PLUGINS.extract(vendored_plugin_dir)?;
+    Ok(())
+}

crates-cli/yaak-cli/src/main.rs

@@ -0,0 +1,331 @@
+mod cli;
+mod commands;
+mod context;
+mod plugin_events;
+mod ui;
+mod utils;
+mod version;
+mod version_check;
+
+use clap::{CommandFactory, FromArgMatches};
+use cli::{AGENT_HINTS, Cli, Commands, PluginCommands, RequestCommands};
+use context::{CliContext, CliExecutionContext};
+use std::path::PathBuf;
+use yaak_models::queries::any_request::AnyRequest;
+
+/// Built at runtime so root `--help` can report whether the installed agent skill is
+/// still in step with this CLI version.
+fn help_footer() -> String {
+    match commands::agent::help_section() {
+        Some(section) => format!("{AGENT_HINTS}\n\n{section}"),
+        None => format!(
+            "{AGENT_HINTS}\n  - Run `yaak agent install` to install the Yaak skill for AI coding agents"
+        ),
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    let matches = Cli::command().after_help(help_footer()).get_matches();
+    let Cli { data_dir, environment, cookie_jar, verbose, log, command } =
+        match Cli::from_arg_matches(&matches) {
+            Ok(cli) => cli,
+            Err(error) => error.exit(),
+        };
+
+    if let Some(log_level) = log {
+        match log_level {
+            Some(level) => {
+                env_logger::Builder::new().filter_level(level.as_filter()).init();
+            }
+            None => {
+                env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info"))
+                    .init();
+            }
+        }
+    }
+
+    let app_id = if cfg!(debug_assertions) { "app.yaak.desktop.dev" } else { "app.yaak.desktop" };
+
+    let data_dir = data_dir.unwrap_or_else(|| resolve_data_dir(app_id));
+
+    version_check::maybe_check_for_updates().await;
+
+    let exit_code = match command {
+        Commands::Agent(args) => commands::agent::run(args),
+        Commands::Response(args) => {
+            let context = CliContext::new(data_dir.clone(), app_id);
+            let exit_code = commands::response::run(&context, args);
+            context.shutdown().await;
+            exit_code
+        }
+        Commands::TemplateFunction(args) => {
+            let mut context = CliContext::new(data_dir.clone(), app_id);
+            context.init_plugins(CliExecutionContext::default()).await;
+            let exit_code = commands::template_function::run(&context, args).await;
+            context.shutdown().await;
+            exit_code
+        }
+        Commands::Auth(args) => commands::auth::run(args).await,
+        Commands::Import(args) => {
+            let mut context = CliContext::new(data_dir.clone(), app_id);
+            let execution_context = CliExecutionContext {
+                workspace_id: args.workspace_id.clone(),
+                ..CliExecutionContext::default()
+            };
+            context.init_plugins(execution_context).await;
+            let exit_code = commands::import_export::run_import(&context, args).await;
+            context.shutdown().await;
+            exit_code
+        }
+        Commands::Export(args) => {
+            let context = CliContext::new(data_dir.clone(), app_id);
+            let exit_code = commands::import_export::run_export(&context, args);
+            context.shutdown().await;
+            exit_code
+        }
+        Commands::Plugin(args) => match args.command {
+            PluginCommands::Build(args) => commands::plugin::run_build(args).await,
+            PluginCommands::Dev(args) => commands::plugin::run_dev(args).await,
+            PluginCommands::Generate(args) => commands::plugin::run_generate(args).await,
+            PluginCommands::Publish(args) => commands::plugin::run_publish(args).await,
+            PluginCommands::Metadata(args) => commands::plugin::run_metadata(args).await,
+            PluginCommands::Install(install_args) => {
+                let mut context = CliContext::new(data_dir.clone(), app_id);
+                context.init_plugins(CliExecutionContext::default()).await;
+                let exit_code = commands::plugin::run_install(&context, install_args).await;
+                context.shutdown().await;
+                exit_code
+            }
+        },
+        Commands::Build(args) => commands::plugin::run_build(args).await,
+        Commands::Dev(args) => commands::plugin::run_dev(args).await,
+        Commands::Generate(args) => commands::plugin::run_generate(args).await,
+        Commands::Publish(args) => commands::plugin::run_publish(args).await,
+        Commands::Send(args) => {
+            let mut context = CliContext::new(data_dir.clone(), app_id);
+            match resolve_send_execution_context(
+                &context,
+                &args.id,
+                environment.as_deref(),
+                cookie_jar.as_deref(),
+            ) {
+                Ok(execution_context) => {
+                    context.init_plugins(execution_context).await;
+                    let exit_code = commands::send::run(
+                        &context,
+                        args,
+                        environment.as_deref(),
+                        cookie_jar.as_deref(),
+                        verbose,
+                    )
+                    .await;
+                    context.shutdown().await;
+                    exit_code
+                }
+                Err(error) => {
+                    eprintln!("Error: {error}");
+                    1
+                }
+            }
+        }
+        Commands::CookieJar(args) => {
+            let context = CliContext::new(data_dir.clone(), app_id);
+            let exit_code = commands::cookie_jar::run(&context, args);
+            context.shutdown().await;
+            exit_code
+        }
+        Commands::Workspace(args) => {
+            let context = CliContext::new(data_dir.clone(), app_id);
+            let exit_code = commands::workspace::run(&context, args);
+            context.shutdown().await;
+            exit_code
+        }
+        Commands::Request(args) => {
+            let mut context = CliContext::new(data_dir.clone(), app_id);
+            let execution_context_result = match &args.command {
+                RequestCommands::Send { request_id } => resolve_request_execution_context(
+                    &context,
+                    request_id,
+                    environment.as_deref(),
+                    cookie_jar.as_deref(),
+                ),
+                _ => Ok(CliExecutionContext::default()),
+            };
+            match execution_context_result {
+                Ok(execution_context) => {
+                    let with_plugins = matches!(
+                        &args.command,
+                        RequestCommands::Send { .. } | RequestCommands::Schema { .. }
+                    );
+                    if with_plugins {
+                        context.init_plugins(execution_context).await;
+                    }
+                    let exit_code = commands::request::run(
+                        &context,
+                        args,
+                        environment.as_deref(),
+                        cookie_jar.as_deref(),
+                        verbose,
+                    )
+                    .await;
+                    context.shutdown().await;
+                    exit_code
+                }
+                Err(error) => {
+                    eprintln!("Error: {error}");
+                    1
+                }
+            }
+        }
+        Commands::Folder(args) => {
+            let context = CliContext::new(data_dir.clone(), app_id);
+            let exit_code = commands::folder::run(&context, args);
+            context.shutdown().await;
+            exit_code
+        }
+        Commands::Environment(args) => {
+            let context = CliContext::new(data_dir.clone(), app_id);
+            let exit_code = commands::environment::run(&context, args);
+            context.shutdown().await;
+            exit_code
+        }
+    };
+
+    if exit_code != 0 {
+        std::process::exit(exit_code);
+    }
+}
+
+fn resolve_send_execution_context(
+    context: &CliContext,
+    id: &str,
+    environment: Option<&str>,
+    explicit_cookie_jar_id: Option<&str>,
+) -> Result<CliExecutionContext, String> {
+    if let Ok(request) = context.db().get_any_request(id) {
+        let (request_id, workspace_id) = match request {
+            AnyRequest::HttpRequest(r) => (Some(r.id), r.workspace_id),
+            AnyRequest::GrpcRequest(r) => (Some(r.id), r.workspace_id),
+            AnyRequest::WebsocketRequest(r) => (Some(r.id), r.workspace_id),
+        };
+        let cookie_jar_id = resolve_cookie_jar_id(context, &workspace_id, explicit_cookie_jar_id)?;
+        return Ok(CliExecutionContext {
+            request_id,
+            workspace_id: Some(workspace_id),
+            environment_id: environment.map(str::to_string),
+            cookie_jar_id,
+        });
+    }
+
+    if let Ok(folder) = context.db().get_folder(id) {
+        let cookie_jar_id =
+            resolve_cookie_jar_id(context, &folder.workspace_id, explicit_cookie_jar_id)?;
+        return Ok(CliExecutionContext {
+            request_id: None,
+            workspace_id: Some(folder.workspace_id),
+            environment_id: environment.map(str::to_string),
+            cookie_jar_id,
+        });
+    }
+
+    if let Ok(workspace) = context.db().get_workspace(id) {
+        let cookie_jar_id = resolve_cookie_jar_id(context, &workspace.id, explicit_cookie_jar_id)?;
+        return Ok(CliExecutionContext {
+            request_id: None,
+            workspace_id: Some(workspace.id),
+            environment_id: environment.map(str::to_string),
+            cookie_jar_id,
+        });
+    }
+
+    Err(format!("Could not resolve ID '{}' as request, folder, or workspace", id))
+}
+
+fn resolve_request_execution_context(
+    context: &CliContext,
+    request_id: &str,
+    environment: Option<&str>,
+    explicit_cookie_jar_id: Option<&str>,
+) -> Result<CliExecutionContext, String> {
+    let request = context
+        .db()
+        .get_any_request(request_id)
+        .map_err(|e| format!("Failed to get request: {e}"))?;
+
+    let workspace_id = match request {
+        AnyRequest::HttpRequest(r) => r.workspace_id,
+        AnyRequest::GrpcRequest(r) => r.workspace_id,
+        AnyRequest::WebsocketRequest(r) => r.workspace_id,
+    };
+    let cookie_jar_id = resolve_cookie_jar_id(context, &workspace_id, explicit_cookie_jar_id)?;
+
+    Ok(CliExecutionContext {
+        request_id: Some(request_id.to_string()),
+        workspace_id: Some(workspace_id),
+        environment_id: environment.map(str::to_string),
+        cookie_jar_id,
+    })
+}
+
+fn resolve_cookie_jar_id(
+    context: &CliContext,
+    workspace_id: &str,
+    explicit_cookie_jar_id: Option<&str>,
+) -> Result<Option<String>, String> {
+    if let Some(cookie_jar_id) = explicit_cookie_jar_id {
+        return Ok(Some(cookie_jar_id.to_string()));
+    }
+
+    let default_cookie_jar = context
+        .db()
+        .list_cookie_jars(workspace_id)
+        .map_err(|e| format!("Failed to list cookie jars: {e}"))?
+        .into_iter()
+        .min_by_key(|jar| jar.created_at)
+        .map(|jar| jar.id);
+    Ok(default_cookie_jar)
+}
+
+fn resolve_data_dir(app_id: &str) -> PathBuf {
+    if let Some(dir) = wsl_data_dir(app_id) {
+        return dir;
+    }
+    dirs::data_dir().expect("Could not determine data directory").join(app_id)
+}
+
+/// Detect WSL and resolve the Windows AppData\Roaming path for the Yaak data directory.
+fn wsl_data_dir(app_id: &str) -> Option<PathBuf> {
+    if !cfg!(target_os = "linux") {
+        return None;
+    }
+
+    let proc_version = std::fs::read_to_string("/proc/version").ok()?;
+    let is_wsl = proc_version.to_lowercase().contains("microsoft");
+    if !is_wsl {
+        return None;
+    }
+
+    // We're in WSL, so try to resolve the Yaak app's data directory in Windows
+
+    // Get the Windows %APPDATA% path via cmd.exe
+    let appdata_output =
+        std::process::Command::new("cmd.exe").args(["/C", "echo", "%APPDATA%"]).output().ok()?;
+
+    let win_path = String::from_utf8(appdata_output.stdout).ok()?.trim().to_string();
+    if win_path.is_empty() || win_path == "%APPDATA%" {
+        return None;
+    }
+
+    // Convert Windows path to WSL path using wslpath (handles custom mount points)
+    let wslpath_output = std::process::Command::new("wslpath").arg(&win_path).output().ok()?;
+
+    let wsl_appdata = String::from_utf8(wslpath_output.stdout).ok()?.trim().to_string();
+    if wsl_appdata.is_empty() {
+        return None;
+    }
+
+    let wsl_path = PathBuf::from(wsl_appdata).join(app_id);
+
+    if wsl_path.exists() { Some(wsl_path) } else { None }
+}

crates-cli/yaak-cli/src/ui.rs

@@ -0,0 +1,42 @@
+use console::style;
+use std::io::{self, IsTerminal};
+
+pub fn info(message: &str) {
+    if io::stdout().is_terminal() {
+        println!("{:<8} {}", style("INFO").cyan().bold(), style(message).cyan());
+    } else {
+        println!("INFO     {message}");
+    }
+}
+
+pub fn warning(message: &str) {
+    if io::stdout().is_terminal() {
+        println!("{:<8} {}", style("WARNING").yellow().bold(), style(message).yellow());
+    } else {
+        println!("WARNING  {message}");
+    }
+}
+
+pub fn warning_stderr(message: &str) {
+    if io::stderr().is_terminal() {
+        eprintln!("{:<8} {}", style("WARNING").yellow().bold(), style(message).yellow());
+    } else {
+        eprintln!("WARNING  {message}");
+    }
+}
+
+pub fn success(message: &str) {
+    if io::stdout().is_terminal() {
+        println!("{:<8} {}", style("SUCCESS").green().bold(), style(message).green());
+    } else {
+        println!("SUCCESS  {message}");
+    }
+}
+
+pub fn error(message: &str) {
+    if io::stderr().is_terminal() {
+        eprintln!("{:<8} {}", style("ERROR").red().bold(), style(message).red());
+    } else {
+        eprintln!("Error: {message}");
+    }
+}

crates-cli/yaak-cli/src/utils/confirm.rs

@@ -0,0 +1,16 @@
+use std::io::{self, IsTerminal, Write};
+
+pub fn confirm_delete(resource_name: &str, resource_id: &str) -> bool {
+    if !io::stdin().is_terminal() {
+        eprintln!("Refusing to delete in non-interactive mode without --yes");
+        std::process::exit(1);
+    }
+
+    print!("Delete {resource_name} {resource_id}? [y/N]: ");
+    io::stdout().flush().expect("Failed to flush stdout");
+
+    let mut input = String::new();
+    io::stdin().read_line(&mut input).expect("Failed to read confirmation");
+
+    matches!(input.trim().to_lowercase().as_str(), "y" | "yes")
+}

crates-cli/yaak-cli/src/utils/http.rs

@@ -0,0 +1,47 @@
+use reqwest::Client;
+use reqwest::header::{HeaderMap, HeaderName, HeaderValue, USER_AGENT};
+use serde_json::Value;
+
+pub fn build_client(session_token: Option<&str>) -> Result<Client, String> {
+    let mut headers = HeaderMap::new();
+    let user_agent = HeaderValue::from_str(&user_agent())
+        .map_err(|e| format!("Failed to build user-agent header: {e}"))?;
+    headers.insert(USER_AGENT, user_agent);
+
+    if let Some(token) = session_token {
+        let token_value = HeaderValue::from_str(token)
+            .map_err(|e| format!("Failed to build session header: {e}"))?;
+        headers.insert(HeaderName::from_static("x-yaak-session"), token_value);
+    }
+
+    Client::builder()
+        .default_headers(headers)
+        .build()
+        .map_err(|e| format!("Failed to initialize HTTP client: {e}"))
+}
+
+pub fn parse_api_error(status: u16, body: &str) -> String {
+    if let Ok(value) = serde_json::from_str::<Value>(body) {
+        if let Some(message) = value.get("message").and_then(Value::as_str) {
+            return message.to_string();
+        }
+        if let Some(error) = value.get("error").and_then(Value::as_str) {
+            return error.to_string();
+        }
+    }
+
+    format!("API error {status}: {body}")
+}
+
+fn user_agent() -> String {
+    format!("YaakCli/{} ({})", crate::version::cli_version(), ua_platform())
+}
+
+fn ua_platform() -> &'static str {
+    match std::env::consts::OS {
+        "windows" => "Win",
+        "darwin" => "Mac",
+        "linux" => "Linux",
+        _ => "Unknown",
+    }
+}

crates-cli/yaak-cli/src/utils/json.rs

@@ -0,0 +1,131 @@
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+use serde_json::{Map, Value};
+
+type JsonResult<T> = std::result::Result<T, String>;
+
+pub fn is_json_shorthand(input: &str) -> bool {
+    input.trim_start().starts_with('{')
+}
+
+pub fn parse_json_object(raw: &str, context: &str) -> JsonResult<Value> {
+    let value: Value = serde_json::from_str(raw)
+        .map_err(|error| format!("Invalid JSON for {context}: {error}"))?;
+
+    if !value.is_object() {
+        return Err(format!("JSON payload for {context} must be an object"));
+    }
+
+    Ok(value)
+}
+
+pub fn parse_optional_json(
+    json_flag: Option<String>,
+    json_shorthand: Option<String>,
+    context: &str,
+) -> JsonResult<Option<Value>> {
+    match (json_flag, json_shorthand) {
+        (Some(_), Some(_)) => {
+            Err(format!("Cannot provide both --json and positional JSON for {context}"))
+        }
+        (Some(raw), None) => parse_json_object(&raw, context).map(Some),
+        (None, Some(raw)) => parse_json_object(&raw, context).map(Some),
+        (None, None) => Ok(None),
+    }
+}
+
+pub fn parse_required_json(
+    json_flag: Option<String>,
+    json_shorthand: Option<String>,
+    context: &str,
+) -> JsonResult<Value> {
+    parse_optional_json(json_flag, json_shorthand, context)?
+        .ok_or_else(|| format!("Missing JSON payload for {context}. Use --json or positional JSON"))
+}
+
+pub fn require_id(payload: &Value, context: &str) -> JsonResult<String> {
+    payload
+        .get("id")
+        .and_then(|value| value.as_str())
+        .filter(|value| !value.is_empty())
+        .map(|value| value.to_string())
+        .ok_or_else(|| format!("{context} requires a non-empty \"id\" field"))
+}
+
+pub fn validate_create_id(payload: &Value, context: &str) -> JsonResult<()> {
+    let Some(id_value) = payload.get("id") else {
+        return Ok(());
+    };
+
+    match id_value {
+        Value::String(id) if id.is_empty() => Ok(()),
+        _ => Err(format!("{context} create JSON must omit \"id\" or set it to an empty string")),
+    }
+}
+
+pub fn merge_workspace_id_arg(
+    workspace_id_from_arg: Option<&str>,
+    payload_workspace_id: &mut String,
+    context: &str,
+) -> JsonResult<()> {
+    if let Some(workspace_id_arg) = workspace_id_from_arg {
+        if payload_workspace_id.is_empty() {
+            *payload_workspace_id = workspace_id_arg.to_string();
+        } else if payload_workspace_id != workspace_id_arg {
+            return Err(format!(
+                "{context} got conflicting workspace_id values between positional arg and JSON payload"
+            ));
+        }
+    }
+
+    if payload_workspace_id.is_empty() {
+        return Err(format!(
+            "{context} requires non-empty \"workspaceId\" in JSON payload or positional workspace_id"
+        ));
+    }
+
+    Ok(())
+}
+
+pub fn apply_merge_patch<T>(existing: &T, patch: &Value, id: &str, context: &str) -> JsonResult<T>
+where
+    T: Serialize + DeserializeOwned,
+{
+    let mut base = serde_json::to_value(existing)
+        .map_err(|error| format!("Failed to serialize existing model for {context}: {error}"))?;
+    merge_patch(&mut base, patch);
+
+    let Some(base_object) = base.as_object_mut() else {
+        return Err(format!("Merged payload for {context} must be an object"));
+    };
+    base_object.insert("id".to_string(), Value::String(id.to_string()));
+
+    serde_json::from_value(base)
+        .map_err(|error| format!("Failed to deserialize merged payload for {context}: {error}"))
+}
+
+fn merge_patch(target: &mut Value, patch: &Value) {
+    match patch {
+        Value::Object(patch_map) => {
+            if !target.is_object() {
+                *target = Value::Object(Map::new());
+            }
+
+            let target_map =
+                target.as_object_mut().expect("merge_patch target expected to be object");
+
+            for (key, patch_value) in patch_map {
+                if patch_value.is_null() {
+                    target_map.remove(key);
+                    continue;
+                }
+
+                let target_entry = target_map.entry(key.clone()).or_insert(Value::Null);
+                merge_patch(target_entry, patch_value);
+            }
+        }
+        _ => {
+            *target = patch.clone();
+        }
+    }
+}

crates-cli/yaak-cli/src/utils/mod.rs

@@ -0,0 +1,5 @@
+pub mod confirm;
+pub mod http;
+pub mod json;
+pub mod schema;
+pub mod workspace;

crates-cli/yaak-cli/src/utils/schema.rs

@@ -0,0 +1,15 @@
+use serde_json::{Value, json};
+
+pub fn append_agent_hints(schema: &mut Value) {
+    let Some(schema_obj) = schema.as_object_mut() else {
+        return;
+    };
+
+    schema_obj.insert(
+        "x-yaak-agent-hints".to_string(),
+        json!({
+            "templateVariableSyntax": "${[ my_var ]}",
+            "templateFunctionSyntax": "${[ namespace.my_func(a='aaa',b='bbb') ]}",
+        }),
+    );
+}

crates-cli/yaak-cli/src/utils/workspace.rs

@@ -0,0 +1,19 @@
+use crate::context::CliContext;
+
+pub fn resolve_workspace_id(
+    ctx: &CliContext,
+    workspace_id: Option<&str>,
+    command_name: &str,
+) -> Result<String, String> {
+    if let Some(workspace_id) = workspace_id {
+        return Ok(workspace_id.to_string());
+    }
+
+    let workspaces =
+        ctx.db().list_workspaces().map_err(|e| format!("Failed to list workspaces: {e}"))?;
+    match workspaces.as_slice() {
+        [] => Err(format!("No workspaces found. {command_name} requires a workspace ID.")),
+        [workspace] => Ok(workspace.id.clone()),
+        _ => Err(format!("Multiple workspaces found. {command_name} requires a workspace ID.")),
+    }
+}

crates-cli/yaak-cli/src/version.rs

@@ -0,0 +1,3 @@
+pub fn cli_version() -> &'static str {
+    option_env!("YAAK_CLI_VERSION").unwrap_or(env!("CARGO_PKG_VERSION"))
+}

crates-cli/yaak-cli/src/version_check.rs

@@ -0,0 +1,225 @@
+use crate::ui;
+use crate::version;
+use serde::{Deserialize, Serialize};
+use std::fs;
+use std::io::IsTerminal;
+use std::path::{Path, PathBuf};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+use yaak_api::{ApiClientKind, yaak_api_client};
+
+const CACHE_FILE_NAME: &str = "cli-version-check.json";
+const CHECK_INTERVAL_SECS: u64 = 24 * 60 * 60;
+const REQUEST_TIMEOUT: Duration = Duration::from_millis(800);
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[serde(default)]
+struct VersionCheckResponse {
+    outdated: bool,
+    latest_version: Option<String>,
+    upgrade_hint: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default)]
+struct CacheRecord {
+    checked_at_epoch_secs: u64,
+    response: VersionCheckResponse,
+    last_warned_at_epoch_secs: Option<u64>,
+    last_warned_version: Option<String>,
+}
+
+impl Default for CacheRecord {
+    fn default() -> Self {
+        Self {
+            checked_at_epoch_secs: 0,
+            response: VersionCheckResponse::default(),
+            last_warned_at_epoch_secs: None,
+            last_warned_version: None,
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct VersionCheckRequest<'a> {
+    current_version: &'a str,
+    channel: String,
+    install_source: String,
+    platform: &'a str,
+    arch: &'a str,
+    // False when stdout is piped, e.g. a coding agent driving the CLI
+    interactive: bool,
+}
+
+pub async fn maybe_check_for_updates() {
+    if should_skip_check() {
+        return;
+    }
+
+    let now = unix_epoch_secs();
+    let cache_path = cache_path();
+    let cached = read_cache(&cache_path);
+
+    if let Some(cache) = cached.as_ref().filter(|c| !is_expired(c.checked_at_epoch_secs, now)) {
+        let mut record = cache.clone();
+        maybe_warn_outdated(&mut record, now);
+        write_cache(&cache_path, &record);
+        return;
+    }
+
+    let fresh = fetch_version_check().await;
+    match fresh {
+        Some(response) => {
+            let mut record = CacheRecord {
+                checked_at_epoch_secs: now,
+                response: response.clone(),
+                last_warned_at_epoch_secs: cached
+                    .as_ref()
+                    .and_then(|c| c.last_warned_at_epoch_secs),
+                last_warned_version: cached.as_ref().and_then(|c| c.last_warned_version.clone()),
+            };
+            maybe_warn_outdated(&mut record, now);
+            write_cache(&cache_path, &record);
+        }
+        None => {
+            let fallback = cached.as_ref().map(|cache| cache.response.clone()).unwrap_or_default();
+            let mut record = CacheRecord {
+                checked_at_epoch_secs: now,
+                response: fallback,
+                last_warned_at_epoch_secs: cached
+                    .as_ref()
+                    .and_then(|c| c.last_warned_at_epoch_secs),
+                last_warned_version: cached.as_ref().and_then(|c| c.last_warned_version.clone()),
+            };
+            maybe_warn_outdated(&mut record, now);
+            write_cache(&cache_path, &record);
+        }
+    }
+}
+
+fn should_skip_check() -> bool {
+    if std::env::var("YAAK_CLI_NO_UPDATE_CHECK")
+        .is_ok_and(|v| v == "1" || v.eq_ignore_ascii_case("true"))
+    {
+        return true;
+    }
+
+    std::env::var("CI").is_ok()
+}
+
+async fn fetch_version_check() -> Option<VersionCheckResponse> {
+    let api_url = format!("{}/cli/check", update_base_url());
+    let current_version = version::cli_version();
+    let payload = VersionCheckRequest {
+        current_version,
+        channel: release_channel(current_version),
+        install_source: install_source(),
+        platform: std::env::consts::OS,
+        arch: std::env::consts::ARCH,
+        interactive: std::io::stdout().is_terminal(),
+    };
+
+    let client = yaak_api_client(ApiClientKind::Cli, current_version).ok()?;
+    let request = client.post(api_url).json(&payload);
+
+    let response = tokio::time::timeout(REQUEST_TIMEOUT, request.send()).await.ok()?.ok()?;
+    if !response.status().is_success() {
+        return None;
+    }
+
+    tokio::time::timeout(REQUEST_TIMEOUT, response.json::<VersionCheckResponse>()).await.ok()?.ok()
+}
+
+fn release_channel(version: &str) -> String {
+    version
+        .split_once('-')
+        .and_then(|(_, suffix)| suffix.split('.').next())
+        .unwrap_or("stable")
+        .to_string()
+}
+
+fn install_source() -> String {
+    std::env::var("YAAK_CLI_INSTALL_SOURCE")
+        .ok()
+        .filter(|s| !s.trim().is_empty())
+        .unwrap_or_else(|| "source".to_string())
+}
+
+fn update_base_url() -> &'static str {
+    match std::env::var("ENVIRONMENT").ok().as_deref() {
+        Some("development") => "http://localhost:9444",
+        _ => "https://update.yaak.app",
+    }
+}
+
+fn maybe_warn_outdated(record: &mut CacheRecord, now: u64) {
+    if !record.response.outdated {
+        return;
+    }
+
+    let latest =
+        record.response.latest_version.clone().unwrap_or_else(|| "a newer release".to_string());
+    let warn_suppressed = record.last_warned_version.as_deref() == Some(latest.as_str())
+        && record.last_warned_at_epoch_secs.is_some_and(|t| !is_expired(t, now));
+    if warn_suppressed {
+        return;
+    }
+
+    let hint = record.response.upgrade_hint.clone().unwrap_or_else(default_upgrade_hint);
+    ui::warning_stderr(&format!("A newer Yaak CLI version is available ({latest}). {hint}"));
+    record.last_warned_version = Some(latest);
+    record.last_warned_at_epoch_secs = Some(now);
+}
+
+fn default_upgrade_hint() -> String {
+    if install_source() == "npm" {
+        let channel = release_channel(version::cli_version());
+        if channel == "stable" {
+            return "Run `npm install -g @yaakapp/cli@latest` to update.".to_string();
+        }
+        return format!("Run `npm install -g @yaakapp/cli@{channel}` to update.");
+    }
+
+    "Update your Yaak CLI installation to the latest release.".to_string()
+}
+
+fn cache_path() -> PathBuf {
+    std::env::temp_dir().join("yaak-cli").join(format!("{}-{CACHE_FILE_NAME}", environment_name()))
+}
+
+fn environment_name() -> &'static str {
+    match std::env::var("ENVIRONMENT").ok().as_deref() {
+        Some("staging") => "staging",
+        Some("development") => "development",
+        _ => "production",
+    }
+}
+
+fn read_cache(path: &Path) -> Option<CacheRecord> {
+    let contents = fs::read_to_string(path).ok()?;
+    serde_json::from_str::<CacheRecord>(&contents).ok()
+}
+
+fn write_cache(path: &Path, record: &CacheRecord) {
+    let Some(parent) = path.parent() else {
+        return;
+    };
+    if fs::create_dir_all(parent).is_err() {
+        return;
+    }
+    let Ok(json) = serde_json::to_string(record) else {
+        return;
+    };
+    let _ = fs::write(path, json);
+}
+
+fn is_expired(checked_at_epoch_secs: u64, now: u64) -> bool {
+    now.saturating_sub(checked_at_epoch_secs) >= CHECK_INTERVAL_SECS
+}
+
+fn unix_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_else(|_| Duration::from_secs(0))
+        .as_secs()
+}