CLI command architecture and DB-backed model update syncing (#397)

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

@@ -0,0 +1,282 @@
+use clap::{Args, Parser, Subcommand};
+use std::path::PathBuf;
+
+#[derive(Parser)]
+#[command(name = "yaakcli")]
+#[command(about = "Yaak CLI - API client from the command line")]
+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>,
+
+    /// Enable verbose logging
+    #[arg(long, short, global = true)]
+    pub verbose: bool,
+
+    #[command(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Subcommand)]
+pub enum Commands {
+    /// Send an HTTP request by ID
+    Send(SendArgs),
+
+    /// Workspace commands
+    Workspace(WorkspaceArgs),
+
+    /// Request commands
+    Request(RequestArgs),
+
+    /// Folder commands
+    Folder(FolderArgs),
+
+    /// Environment commands
+    Environment(EnvironmentArgs),
+}
+
+#[derive(Args)]
+pub struct SendArgs {
+    /// Request ID
+    pub request_id: String,
+}
+
+#[derive(Args)]
+pub struct WorkspaceArgs {
+    #[command(subcommand)]
+    pub command: WorkspaceCommands,
+}
+
+#[derive(Subcommand)]
+pub enum WorkspaceCommands {
+    /// List all workspaces
+    List,
+
+    /// 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)]
+pub struct RequestArgs {
+    #[command(subcommand)]
+    pub command: RequestCommands,
+}
+
+#[derive(Subcommand)]
+pub enum RequestCommands {
+    /// List requests in a workspace
+    List {
+        /// Workspace ID
+        workspace_id: String,
+    },
+
+    /// Show a request as JSON
+    Show {
+        /// Request ID
+        request_id: String,
+    },
+
+    /// Send an HTTP request by ID
+    Send {
+        /// Request ID
+        request_id: String,
+    },
+
+    /// 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(Args)]
+pub struct FolderArgs {
+    #[command(subcommand)]
+    pub command: FolderCommands,
+}
+
+#[derive(Subcommand)]
+pub enum FolderCommands {
+    /// List folders in a workspace
+    List {
+        /// Workspace ID
+        workspace_id: String,
+    },
+
+    /// 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)]
+pub struct EnvironmentArgs {
+    #[command(subcommand)]
+    pub command: EnvironmentCommands,
+}
+
+#[derive(Subcommand)]
+pub enum EnvironmentCommands {
+    /// List environments in a workspace
+    List {
+        /// Workspace ID
+        workspace_id: String,
+    },
+
+    /// Show an environment as JSON
+    Show {
+        /// Environment ID
+        environment_id: String,
+    },
+
+    /// Create an environment
+    Create {
+        /// Workspace ID (or positional JSON payload shorthand)
+        workspace_id: Option<String>,
+
+        /// Environment name
+        #[arg(short, long)]
+        name: Option<String>,
+
+        /// JSON payload
+        #[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,
+    },
+}

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

@@ -0,0 +1,159 @@
+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, parse_optional_json, parse_required_json, require_id,
+    validate_create_id,
+};
+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),
+        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 list(ctx: &CliContext, workspace_id: &str) -> CommandResult {
+    let environments = ctx
+        .db()
+        .list_environments_ensure_base(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 {
+    if json.is_some() && workspace_id.as_deref().is_some_and(|v| !is_json_shorthand(v)) {
+        return Err(
+            "environment create cannot combine workspace_id with --json payload".to_string()
+        );
+    }
+
+    let payload = parse_optional_json(
+        json,
+        workspace_id.clone().filter(|v| is_json_shorthand(v)),
+        "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}"))?;
+
+        if environment.workspace_id.is_empty() {
+            return Err("environment create JSON requires non-empty \"workspaceId\"".to_string());
+        }
+
+        if environment.parent_model.is_empty() {
+            environment.parent_model = "environment".to_string();
+        }
+
+        let created = ctx
+            .db()
+            .upsert_environment(&environment, &UpdateSource::Sync)
+            .map_err(|e| format!("Failed to create environment: {e}"))?;
+
+        println!("Created environment: {}", created.id);
+        return Ok(());
+    }
+
+    let workspace_id = workspace_id.ok_or_else(|| {
+        "environment create requires workspace_id unless JSON payload is provided".to_string()
+    })?;
+    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
+        .db()
+        .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
+        .db()
+        .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
+        .db()
+        .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,139 @@
+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, parse_optional_json, parse_required_json, require_id,
+    validate_create_id,
+};
+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),
+        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 list(ctx: &CliContext, workspace_id: &str) -> CommandResult {
+    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 {
+    if json.is_some() && workspace_id.as_deref().is_some_and(|v| !is_json_shorthand(v)) {
+        return Err("folder create cannot combine workspace_id with --json payload".to_string());
+    }
+
+    let payload = parse_optional_json(
+        json,
+        workspace_id.clone().filter(|v| is_json_shorthand(v)),
+        "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 folder: Folder =
+            serde_json::from_value(payload).map_err(|e| format!("Failed to parse folder create JSON: {e}"))?;
+
+        if folder.workspace_id.is_empty() {
+            return Err("folder create JSON requires non-empty \"workspaceId\"".to_string());
+        }
+
+        let created = ctx
+            .db()
+            .upsert_folder(&folder, &UpdateSource::Sync)
+            .map_err(|e| format!("Failed to create folder: {e}"))?;
+
+        println!("Created folder: {}", created.id);
+        return Ok(());
+    }
+
+    let workspace_id = workspace_id
+        .ok_or_else(|| "folder create requires workspace_id unless JSON payload is provided".to_string())?;
+    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
+        .db()
+        .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
+        .db()
+        .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
+        .db()
+        .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/mod.rs

@@ -0,0 +1,5 @@
+pub mod environment;
+pub mod folder;
+pub mod request;
+pub mod send;
+pub mod workspace;

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

@@ -0,0 +1,233 @@
+use crate::cli::{RequestArgs, RequestCommands};
+use crate::context::CliContext;
+use crate::utils::confirm::confirm_delete;
+use crate::utils::json::{
+    apply_merge_patch, is_json_shorthand, parse_optional_json, parse_required_json, require_id,
+    validate_create_id,
+};
+use tokio::sync::mpsc;
+use yaak::send::{SendHttpRequestByIdWithPluginsParams, send_http_request_by_id_with_plugins};
+use yaak_models::models::HttpRequest;
+use yaak_models::util::UpdateSource;
+use yaak_plugins::events::PluginContext;
+
+type CommandResult<T = ()> = std::result::Result<T, String>;
+
+pub async fn run(
+    ctx: &CliContext,
+    args: RequestArgs,
+    environment: Option<&str>,
+    verbose: bool,
+) -> i32 {
+    let result = match args.command {
+        RequestCommands::List { workspace_id } => list(ctx, &workspace_id),
+        RequestCommands::Show { request_id } => show(ctx, &request_id),
+        RequestCommands::Send { request_id } => {
+            return match send_request_by_id(ctx, &request_id, environment, verbose).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: &str) -> CommandResult {
+    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(())
+}
+
+fn create(
+    ctx: &CliContext,
+    workspace_id: Option<String>,
+    name: Option<String>,
+    method: Option<String>,
+    url: Option<String>,
+    json: Option<String>,
+) -> CommandResult {
+    if json.is_some() && workspace_id.as_deref().is_some_and(|v| !is_json_shorthand(v)) {
+        return Err("request create cannot combine workspace_id with --json payload".to_string());
+    }
+
+    let payload = parse_optional_json(
+        json,
+        workspace_id.clone().filter(|v| is_json_shorthand(v)),
+        "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")?;
+        let request: HttpRequest = serde_json::from_value(payload)
+            .map_err(|e| format!("Failed to parse request create JSON: {e}"))?;
+
+        if request.workspace_id.is_empty() {
+            return Err("request create JSON requires non-empty \"workspaceId\"".to_string());
+        }
+
+        let created = ctx
+            .db()
+            .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 = workspace_id.ok_or_else(|| {
+        "request create requires workspace_id unless JSON payload is provided".to_string()
+    })?;
+    let name = name.unwrap_or_default();
+    let url = url.unwrap_or_default();
+    let method = method.unwrap_or_else(|| "GET".to_string());
+
+    let request = HttpRequest {
+        workspace_id,
+        name,
+        method: method.to_uppercase(),
+        url,
+        ..Default::default()
+    };
+
+    let created = ctx
+        .db()
+        .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")?;
+
+    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
+        .db()
+        .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
+        .db()
+        .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>,
+    verbose: bool,
+) -> Result<(), String> {
+    let request =
+        ctx.db().get_http_request(request_id).map_err(|e| format!("Failed to get request: {e}"))?;
+
+    let plugin_context = PluginContext::new(None, Some(request.workspace_id.clone()));
+
+    let (event_tx, mut event_rx) = mpsc::channel(100);
+    let event_handle = tokio::spawn(async move {
+        while let Some(event) = event_rx.recv().await {
+            if verbose {
+                println!("{}", event);
+            }
+        }
+    });
+    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: None,
+        response_dir: &response_dir,
+        emit_events_to: Some(event_tx),
+        plugin_manager: ctx.plugin_manager(),
+        encryption_manager: ctx.encryption_manager.clone(),
+        plugin_context: &plugin_context,
+        cancelled_rx: None,
+        connection_manager: None,
+    })
+    .await;
+
+    let _ = event_handle.await;
+    let result = result.map_err(|e| e.to_string())?;
+
+    if verbose {
+        println!();
+    }
+    println!(
+        "HTTP {} {}",
+        result.response.status,
+        result.response.status_reason.as_deref().unwrap_or("")
+    );
+    if verbose {
+        for header in &result.response.headers {
+            println!("{}: {}", header.name, header.value);
+        }
+        println!();
+    }
+    let body = String::from_utf8(result.response_body)
+        .map_err(|e| format!("Failed to read response body: {e}"))?;
+    println!("{}", body);
+    Ok(())
+}

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

@@ -0,0 +1,18 @@
+use crate::cli::SendArgs;
+use crate::commands::request;
+use crate::context::CliContext;
+
+pub async fn run(
+    ctx: &CliContext,
+    args: SendArgs,
+    environment: Option<&str>,
+    verbose: bool,
+) -> i32 {
+    match request::send_request_by_id(ctx, &args.request_id, environment, verbose).await {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("Error: {error}");
+            1
+        }
+    }
+}

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

@@ -0,0 +1,121 @@
+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 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::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 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
+            .db()
+            .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
+        .db()
+        .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
+        .db()
+        .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
+        .db()
+        .delete_workspace_by_id(workspace_id, &UpdateSource::Sync)
+        .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,96 @@
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use yaak_crypto::manager::EncryptionManager;
+use yaak_models::blob_manager::BlobManager;
+use yaak_models::db_context::DbContext;
+use yaak_models::query_manager::QueryManager;
+use yaak_plugins::events::PluginContext;
+use yaak_plugins::manager::PluginManager;
+
+pub struct CliContext {
+    data_dir: PathBuf,
+    query_manager: QueryManager,
+    blob_manager: BlobManager,
+    pub encryption_manager: Arc<EncryptionManager>,
+    plugin_manager: Option<Arc<PluginManager>>,
+}
+
+impl CliContext {
+    pub async fn initialize(data_dir: PathBuf, app_id: &str, with_plugins: bool) -> Self {
+        let db_path = data_dir.join("db.sqlite");
+        let blob_path = data_dir.join("blobs.sqlite");
+
+        let (query_manager, blob_manager, _rx) = yaak_models::init_standalone(&db_path, &blob_path)
+            .expect("Failed to initialize database");
+
+        let encryption_manager = Arc::new(EncryptionManager::new(query_manager.clone(), app_id));
+
+        let plugin_manager = if with_plugins {
+            let vendored_plugin_dir = data_dir.join("vendored-plugins");
+            let installed_plugin_dir = data_dir.join("installed-plugins");
+            let node_bin_path = PathBuf::from("node");
+
+            let plugin_runtime_main =
+                std::env::var("YAAK_PLUGIN_RUNTIME").map(PathBuf::from).unwrap_or_else(|_| {
+                    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+                        .join("../../crates-tauri/yaak-app/vendored/plugin-runtime/index.cjs")
+                });
+
+            let plugin_manager = Arc::new(
+                PluginManager::new(
+                    vendored_plugin_dir,
+                    installed_plugin_dir,
+                    node_bin_path,
+                    plugin_runtime_main,
+                    false,
+                )
+                .await,
+            );
+
+            let plugins = query_manager.connect().list_plugins().unwrap_or_default();
+            if !plugins.is_empty() {
+                let errors = plugin_manager
+                    .initialize_all_plugins(plugins, &PluginContext::new_empty())
+                    .await;
+                for (plugin_dir, error_msg) in errors {
+                    eprintln!(
+                        "Warning: Failed to initialize plugin '{}': {}",
+                        plugin_dir, error_msg
+                    );
+                }
+            }
+
+            Some(plugin_manager)
+        } else {
+            None
+        };
+
+        Self { data_dir, query_manager, blob_manager, encryption_manager, plugin_manager }
+    }
+
+    pub fn data_dir(&self) -> &Path {
+        &self.data_dir
+    }
+
+    pub fn db(&self) -> DbContext<'_> {
+        self.query_manager.connect()
+    }
+
+    pub fn query_manager(&self) -> &QueryManager {
+        &self.query_manager
+    }
+
+    pub fn blob_manager(&self) -> &BlobManager {
+        &self.blob_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 {
+            plugin_manager.terminate().await;
+        }
+    }
+}

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

@@ -1,409 +1,49 @@
-use clap::{Parser, Subcommand};
-use log::info;
-use serde_json::Value;
-use std::collections::BTreeMap;
-use std::path::PathBuf;
-use std::sync::Arc;
-use tokio::sync::mpsc;
-use yaak_crypto::manager::EncryptionManager;
-use yaak_http::path_placeholders::apply_path_placeholders;
-use yaak_http::sender::{HttpSender, ReqwestSender};
-use yaak_http::types::{SendableHttpRequest, SendableHttpRequestOptions};
-use yaak_models::models::{HttpRequest, HttpRequestHeader, HttpUrlParameter};
-use yaak_models::render::make_vars_hashmap;
-use yaak_models::util::UpdateSource;
-use yaak_plugins::events::{PluginContext, RenderPurpose};
-use yaak_plugins::manager::PluginManager;
-use yaak_plugins::template_callback::PluginTemplateCallback;
-use yaak_templates::{RenderOptions, parse_and_render, render_json_value_raw};
+mod cli;
+mod commands;
+mod context;
+mod utils;
 
-#[derive(Parser)]
-#[command(name = "yaakcli")]
-#[command(about = "Yaak CLI - API client from the command line")]
-struct Cli {
-    /// Use a custom data directory
-    #[arg(long, global = true)]
-    data_dir: Option<PathBuf>,
-
-    /// Environment ID to use for variable substitution
-    #[arg(long, short, global = true)]
-    environment: Option<String>,
-
-    /// Enable verbose logging
-    #[arg(long, short, global = true)]
-    verbose: bool,
-
-    #[command(subcommand)]
-    command: Commands,
-}
-
-#[derive(Subcommand)]
-enum Commands {
-    /// List all workspaces
-    Workspaces,
-    /// List requests in a workspace
-    Requests {
-        /// Workspace ID
-        workspace_id: String,
-    },
-    /// Send an HTTP request by ID
-    Send {
-        /// Request ID
-        request_id: String,
-    },
-    /// Send a GET request to a URL
-    Get {
-        /// URL to request
-        url: String,
-    },
-    /// Create a new HTTP request
-    Create {
-        /// Workspace ID
-        workspace_id: String,
-        /// Request name
-        #[arg(short, long)]
-        name: String,
-        /// HTTP method
-        #[arg(short, long, default_value = "GET")]
-        method: String,
-        /// URL
-        #[arg(short, long)]
-        url: String,
-    },
-}
-
-/// Render an HTTP request with template variables and plugin functions
-async fn render_http_request(
-    r: &HttpRequest,
-    environment_chain: Vec<yaak_models::models::Environment>,
-    cb: &PluginTemplateCallback,
-    opt: &RenderOptions,
-) -> yaak_templates::error::Result<HttpRequest> {
-    let vars = &make_vars_hashmap(environment_chain);
-
-    let mut url_parameters = Vec::new();
-    for p in r.url_parameters.clone() {
-        if !p.enabled {
-            continue;
-        }
-        url_parameters.push(HttpUrlParameter {
-            enabled: p.enabled,
-            name: parse_and_render(p.name.as_str(), vars, cb, opt).await?,
-            value: parse_and_render(p.value.as_str(), vars, cb, opt).await?,
-            id: p.id,
-        })
-    }
-
-    let mut headers = Vec::new();
-    for p in r.headers.clone() {
-        if !p.enabled {
-            continue;
-        }
-        headers.push(HttpRequestHeader {
-            enabled: p.enabled,
-            name: parse_and_render(p.name.as_str(), vars, cb, opt).await?,
-            value: parse_and_render(p.value.as_str(), vars, cb, opt).await?,
-            id: p.id,
-        })
-    }
-
-    let mut body = BTreeMap::new();
-    for (k, v) in r.body.clone() {
-        body.insert(k, render_json_value_raw(v, vars, cb, opt).await?);
-    }
-
-    let authentication = {
-        let mut disabled = false;
-        let mut auth = BTreeMap::new();
-        match r.authentication.get("disabled") {
-            Some(Value::Bool(true)) => {
-                disabled = true;
-            }
-            Some(Value::String(tmpl)) => {
-                disabled = parse_and_render(tmpl.as_str(), vars, cb, opt)
-                    .await
-                    .unwrap_or_default()
-                    .is_empty();
-                info!(
-                    "Rendering authentication.disabled as a template: {disabled} from \"{tmpl}\""
-                );
-            }
-            _ => {}
-        }
-        if disabled {
-            auth.insert("disabled".to_string(), Value::Bool(true));
-        } else {
-            for (k, v) in r.authentication.clone() {
-                if k == "disabled" {
-                    auth.insert(k, Value::Bool(false));
-                } else {
-                    auth.insert(k, render_json_value_raw(v, vars, cb, opt).await?);
-                }
-            }
-        }
-        auth
-    };
-
-    let url = parse_and_render(r.url.clone().as_str(), vars, cb, opt).await?;
-
-    // Apply path placeholders (e.g., /users/:id -> /users/123)
-    let (url, url_parameters) = apply_path_placeholders(&url, &url_parameters);
-
-    Ok(HttpRequest { url, url_parameters, headers, body, authentication, ..r.to_owned() })
-}
+use clap::Parser;
+use cli::{Cli, Commands, RequestCommands};
+use context::CliContext;
 
 #[tokio::main]
 async fn main() {
-    let cli = Cli::parse();
+    let Cli { data_dir, environment, verbose, command } = Cli::parse();
 
-    // Initialize logging
-    if cli.verbose {
+    if verbose {
         env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
     }
 
-    // Use the same app_id for both data directory and keyring
     let app_id = if cfg!(debug_assertions) { "app.yaak.desktop.dev" } else { "app.yaak.desktop" };
 
-    let data_dir = cli.data_dir.unwrap_or_else(|| {
+    let data_dir = data_dir.unwrap_or_else(|| {
         dirs::data_dir().expect("Could not determine data directory").join(app_id)
     });
 
-    let db_path = data_dir.join("db.sqlite");
-    let blob_path = data_dir.join("blobs.sqlite");
-
-    let (query_manager, _blob_manager, _rx) =
-        yaak_models::init_standalone(&db_path, &blob_path).expect("Failed to initialize database");
-
-    let db = query_manager.connect();
-
-    // Initialize encryption manager for secure() template function
-    // Use the same app_id as the Tauri app for keyring access
-    let encryption_manager = Arc::new(EncryptionManager::new(query_manager.clone(), app_id));
-
-    // Initialize plugin manager for template functions
-    let vendored_plugin_dir = data_dir.join("vendored-plugins");
-    let installed_plugin_dir = data_dir.join("installed-plugins");
-
-    // Use system node for CLI (must be in PATH)
-    let node_bin_path = PathBuf::from("node");
-
-    // Find the plugin runtime - check YAAK_PLUGIN_RUNTIME env var, then fallback to development path
-    let plugin_runtime_main =
-        std::env::var("YAAK_PLUGIN_RUNTIME").map(PathBuf::from).unwrap_or_else(|_| {
-            // Development fallback: look relative to crate root
-            PathBuf::from(env!("CARGO_MANIFEST_DIR"))
-                .join("../../crates-tauri/yaak-app/vendored/plugin-runtime/index.cjs")
-        });
-
-    // Create plugin manager (plugins may not be available in CLI context)
-    let plugin_manager = Arc::new(
-        PluginManager::new(
-            vendored_plugin_dir,
-            installed_plugin_dir,
-            node_bin_path,
-            plugin_runtime_main,
-            false,
-        )
-        .await,
+    let needs_plugins = matches!(
+        &command,
+        Commands::Send(_)
+            | Commands::Request(cli::RequestArgs { command: RequestCommands::Send { .. } })
     );
 
-    // Initialize plugins from database
-    let plugins = db.list_plugins().unwrap_or_default();
-    if !plugins.is_empty() {
-        let errors =
-            plugin_manager.initialize_all_plugins(plugins, &PluginContext::new_empty()).await;
-        for (plugin_dir, error_msg) in errors {
-            eprintln!("Warning: Failed to initialize plugin '{}': {}", plugin_dir, error_msg);
+    let context = CliContext::initialize(data_dir, app_id, needs_plugins).await;
+
+    let exit_code = match command {
+        Commands::Send(args) => {
+            commands::send::run(&context, args, environment.as_deref(), verbose).await
         }
+        Commands::Workspace(args) => commands::workspace::run(&context, args),
+        Commands::Request(args) => {
+            commands::request::run(&context, args, environment.as_deref(), verbose).await
+        }
+        Commands::Folder(args) => commands::folder::run(&context, args),
+        Commands::Environment(args) => commands::environment::run(&context, args),
+    };
+
+    context.shutdown().await;
+
+    if exit_code != 0 {
+        std::process::exit(exit_code);
     }
-
-    match cli.command {
-        Commands::Workspaces => {
-            let workspaces = db.list_workspaces().expect("Failed to list workspaces");
-            if workspaces.is_empty() {
-                println!("No workspaces found");
-            } else {
-                for ws in workspaces {
-                    println!("{} - {}", ws.id, ws.name);
-                }
-            }
-        }
-        Commands::Requests { workspace_id } => {
-            let requests = db.list_http_requests(&workspace_id).expect("Failed to list requests");
-            if requests.is_empty() {
-                println!("No requests found in workspace {}", workspace_id);
-            } else {
-                for req in requests {
-                    println!("{} - {} {}", req.id, req.method, req.name);
-                }
-            }
-        }
-        Commands::Send { request_id } => {
-            let request = db.get_http_request(&request_id).expect("Failed to get request");
-
-            // Resolve environment chain for variable substitution
-            let environment_chain = db
-                .resolve_environments(
-                    &request.workspace_id,
-                    request.folder_id.as_deref(),
-                    cli.environment.as_deref(),
-                )
-                .unwrap_or_default();
-
-            // Create template callback with plugin support
-            let plugin_context = PluginContext::new(None, Some(request.workspace_id.clone()));
-            let template_callback = PluginTemplateCallback::new(
-                plugin_manager.clone(),
-                encryption_manager.clone(),
-                &plugin_context,
-                RenderPurpose::Send,
-            );
-
-            // Render templates in the request
-            let rendered_request = render_http_request(
-                &request,
-                environment_chain,
-                &template_callback,
-                &RenderOptions::throw(),
-            )
-            .await
-            .expect("Failed to render request templates");
-
-            if cli.verbose {
-                println!("> {} {}", rendered_request.method, rendered_request.url);
-            }
-
-            // Convert to sendable request
-            let sendable = SendableHttpRequest::from_http_request(
-                &rendered_request,
-                SendableHttpRequestOptions::default(),
-            )
-            .await
-            .expect("Failed to build request");
-
-            // Create event channel for progress
-            let (event_tx, mut event_rx) = mpsc::channel(100);
-
-            // Spawn task to print events if verbose
-            let verbose = cli.verbose;
-            let verbose_handle = if verbose {
-                Some(tokio::spawn(async move {
-                    while let Some(event) = event_rx.recv().await {
-                        println!("{}", event);
-                    }
-                }))
-            } else {
-                // Drain events silently
-                tokio::spawn(async move { while event_rx.recv().await.is_some() {} });
-                None
-            };
-
-            // Send the request
-            let sender = ReqwestSender::new().expect("Failed to create HTTP client");
-            let response = sender.send(sendable, event_tx).await.expect("Failed to send request");
-
-            // Wait for event handler to finish
-            if let Some(handle) = verbose_handle {
-                let _ = handle.await;
-            }
-
-            // Print response
-            if verbose {
-                println!();
-            }
-            println!(
-                "HTTP {} {}",
-                response.status,
-                response.status_reason.as_deref().unwrap_or("")
-            );
-
-            if verbose {
-                for (name, value) in &response.headers {
-                    println!("{}: {}", name, value);
-                }
-                println!();
-            }
-
-            // Print body
-            let (body, _stats) = response.text().await.expect("Failed to read response body");
-            println!("{}", body);
-        }
-        Commands::Get { url } => {
-            if cli.verbose {
-                println!("> GET {}", url);
-            }
-
-            // Build a simple GET request
-            let sendable = SendableHttpRequest {
-                url: url.clone(),
-                method: "GET".to_string(),
-                headers: vec![],
-                body: None,
-                options: SendableHttpRequestOptions::default(),
-            };
-
-            // Create event channel for progress
-            let (event_tx, mut event_rx) = mpsc::channel(100);
-
-            // Spawn task to print events if verbose
-            let verbose = cli.verbose;
-            let verbose_handle = if verbose {
-                Some(tokio::spawn(async move {
-                    while let Some(event) = event_rx.recv().await {
-                        println!("{}", event);
-                    }
-                }))
-            } else {
-                tokio::spawn(async move { while event_rx.recv().await.is_some() {} });
-                None
-            };
-
-            // Send the request
-            let sender = ReqwestSender::new().expect("Failed to create HTTP client");
-            let response = sender.send(sendable, event_tx).await.expect("Failed to send request");
-
-            if let Some(handle) = verbose_handle {
-                let _ = handle.await;
-            }
-
-            // Print response
-            if verbose {
-                println!();
-            }
-            println!(
-                "HTTP {} {}",
-                response.status,
-                response.status_reason.as_deref().unwrap_or("")
-            );
-
-            if verbose {
-                for (name, value) in &response.headers {
-                    println!("{}: {}", name, value);
-                }
-                println!();
-            }
-
-            // Print body
-            let (body, _stats) = response.text().await.expect("Failed to read response body");
-            println!("{}", body);
-        }
-        Commands::Create { workspace_id, name, method, url } => {
-            let request = HttpRequest {
-                workspace_id,
-                name,
-                method: method.to_uppercase(),
-                url,
-                ..Default::default()
-            };
-
-            let created = db
-                .upsert_http_request(&request, &UpdateSource::Sync)
-                .expect("Failed to create request");
-
-            println!("Created request: {}", created.id);
-        }
-    }
-
-    // Terminate plugin manager gracefully
-    plugin_manager.terminate().await;
 }

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/json.rs

@@ -0,0 +1,110 @@
+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 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,2 @@
+pub mod confirm;
+pub mod json;