Improve CLI streaming output, logging flags, and schema/help ergonomics

.github/workflows/release-cli-npm.yml

@@ -109,6 +109,21 @@ jobs:
           name: vendored-assets
           path: crates-tauri/yaak-app/vendored
 
+      - name: Set CLI build version
+        shell: bash
+        env:
+          WORKFLOW_VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="$WORKFLOW_VERSION"
+          else
+            VERSION="${GITHUB_REF_NAME#yaak-cli-}"
+          fi
+          VERSION="${VERSION#v}"
+          echo "Building yaak version: $VERSION"
+          echo "YAAK_CLI_VERSION=$VERSION" >> "$GITHUB_ENV"
+
       - name: Build yaak
         run: cargo build --locked --release -p yaak-cli --bin yaak --target ${{ matrix.target }}
 

crates-cli/yaak-cli/README.md

@@ -8,7 +8,9 @@ Current top-level commands:
 
 ```text
 yaakcli send <request_id>
+yaakcli agent-help
 yaakcli workspace list
+yaakcli workspace schema [--pretty]
 yaakcli workspace show <workspace_id>
 yaakcli workspace create --name <name>
 yaakcli workspace create --json '{"name":"My Workspace"}'
@@ -31,6 +33,7 @@ yaakcli folder create '{"workspaceId":"wk_abc","name":"Auth"}'
 yaakcli folder update --json '{"id":"fl_abc","name":"Auth v2"}'
 yaakcli folder delete <folder_id> [--yes]
 yaakcli environment list <workspace_id>
+yaakcli environment schema [--pretty]
 yaakcli environment show <environment_id>
 yaakcli environment create <workspace_id> --name <name>
 yaakcli environment create --json '{"workspaceId":"wk_abc","name":"Production"}'
@@ -43,7 +46,8 @@ Global options:
 
 - `--data-dir <path>`: use a custom data directory
 - `-e, --environment <id>`: environment to use during request rendering/sending
-- `-v, --verbose`: verbose logging and send output
+- `-v, --verbose`: verbose send output (events and streamed response body)
+- `--log [level]`: enable CLI logging; optional level is `error|warn|info|debug|trace`
 
 Notes:
 
@@ -51,6 +55,8 @@ Notes:
 - `delete` commands prompt for confirmation unless `--yes` is provided.
 - In non-interactive mode, `delete` commands require `--yes`.
 - `create` and `update` commands support `--json` and positional JSON shorthand.
+- For `create` commands, use one input mode at a time. Example: do not combine `<workspace_id>` with `--json`.
+- Template tags use `${[ ... ]}` syntax (for example `${[API_BASE_URL]}`), not `{{ ... }}`.
 - `update` uses JSON Merge Patch semantics (RFC 7386) for partial updates.
 
 ## Examples

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

@@ -4,7 +4,14 @@ use std::path::PathBuf;
 #[derive(Parser)]
 #[command(name = "yaak")]
 #[command(about = "Yaak CLI - API client from the command line")]
-#[command(version)]
+#[command(version = crate::version::cli_version())]
+#[command(disable_help_subcommand = true)]
+#[command(after_help = 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)
+  "#)]
 pub struct Cli {
     /// Use a custom data directory
     #[arg(long, global = true)]
@@ -14,10 +21,14 @@ pub struct Cli {
     #[arg(long, short, global = true)]
     pub environment: Option<String>,
 
-    /// Enable verbose logging
+    /// 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,
 }
@@ -71,6 +82,7 @@ pub struct SendArgs {
 }
 
 #[derive(Args)]
+#[command(disable_help_subcommand = true)]
 pub struct WorkspaceArgs {
     #[command(subcommand)]
     pub command: WorkspaceCommands,
@@ -81,6 +93,13 @@ 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
@@ -125,6 +144,7 @@ pub enum WorkspaceCommands {
 }
 
 #[derive(Args)]
+#[command(disable_help_subcommand = true)]
 pub struct RequestArgs {
     #[command(subcommand)]
     pub command: RequestCommands,
@@ -154,6 +174,10 @@ pub enum RequestCommands {
     Schema {
         #[arg(value_enum)]
         request_type: RequestSchemaType,
+
+        /// Pretty-print schema JSON output
+        #[arg(long)]
+        pretty: bool,
     },
 
     /// Create a new HTTP request
@@ -207,7 +231,29 @@ pub enum RequestSchemaType {
     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,
@@ -264,6 +310,7 @@ pub enum FolderCommands {
 }
 
 #[derive(Args)]
+#[command(disable_help_subcommand = true)]
 pub struct EnvironmentArgs {
     #[command(subcommand)]
     pub command: EnvironmentCommands,
@@ -277,6 +324,13 @@ pub enum EnvironmentCommands {
         workspace_id: 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
@@ -284,15 +338,22 @@ pub enum EnvironmentCommands {
     },
 
     /// 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"}'
+
+Do not combine <workspace_id> with --json."#)]
     Create {
-        /// Workspace ID (or positional JSON payload shorthand)
+        /// 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
+        /// JSON payload (use instead of WORKSPACE_ID/--name)
         #[arg(long)]
         json: Option<String>,
     },
@@ -320,6 +381,7 @@ pub enum EnvironmentCommands {
 }
 
 #[derive(Args)]
+#[command(disable_help_subcommand = true)]
 pub struct AuthArgs {
     #[command(subcommand)]
     pub command: AuthCommands,
@@ -338,6 +400,7 @@ pub enum AuthCommands {
 }
 
 #[derive(Args)]
+#[command(disable_help_subcommand = true)]
 pub struct PluginArgs {
     #[command(subcommand)]
     pub command: PluginCommands,

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

@@ -1,5 +1,6 @@
 use crate::cli::{AuthArgs, AuthCommands};
 use crate::ui;
+use crate::utils::http;
 use base64::Engine as _;
 use keyring::Entry;
 use rand::RngCore;
@@ -136,10 +137,8 @@ async fn whoami() -> CommandResult {
     };
 
     let url = format!("{}/api/v1/whoami", environment.api_base_url());
-    let response = reqwest::Client::new()
+    let response = http::build_client(Some(&token))?
         .get(url)
-        .header("X-Yaak-Session", token)
-        .header(reqwest::header::USER_AGENT, user_agent())
         .send()
         .await
         .map_err(|e| format!("Failed to call whoami endpoint: {e}"))?;
@@ -156,7 +155,7 @@ async fn whoami() -> CommandResult {
                     .to_string(),
             );
         }
-        return Err(parse_api_error(status.as_u16(), &body));
+        return Err(http::parse_api_error(status.as_u16(), &body));
     }
 
     println!("{body}");
@@ -342,9 +341,8 @@ async fn write_redirect(stream: &mut TcpStream, location: &str) -> std::io::Resu
 }
 
 async fn exchange_access_token(oauth: &OAuthFlow, code: &str) -> CommandResult<String> {
-    let response = reqwest::Client::new()
+    let response = http::build_client(None)?
         .post(&oauth.token_url)
-        .header(reqwest::header::USER_AGENT, user_agent())
         .form(&[
             ("grant_type", "authorization_code"),
             ("client_id", OAUTH_CLIENT_ID),
@@ -406,38 +404,12 @@ fn delete_auth_token(environment: Environment) -> CommandResult {
     }
 }
 
-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 random_hex(bytes: usize) -> String {
     let mut data = vec![0_u8; bytes];
     OsRng.fill_bytes(&mut data);
     hex::encode(data)
 }
 
-fn user_agent() -> String {
-    format!("YaakCli/{} ({})", env!("CARGO_PKG_VERSION"), ua_platform())
-}
-
-fn ua_platform() -> &'static str {
-    match std::env::consts::OS {
-        "windows" => "Win",
-        "darwin" => "Mac",
-        "linux" => "Linux",
-        _ => "Unknown",
-    }
-}
-
 fn confirm_open_browser() -> CommandResult<bool> {
     if !io::stdin().is_terminal() {
         return Ok(true);

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

@@ -5,6 +5,8 @@ use crate::utils::json::{
     apply_merge_patch, is_json_shorthand, 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::Environment;
 use yaak_models::util::UpdateSource;
 
@@ -13,6 +15,7 @@ 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::Schema { pretty } => schema(pretty),
         EnvironmentCommands::Show { environment_id } => show(ctx, &environment_id),
         EnvironmentCommands::Create { workspace_id, name, json } => {
             create(ctx, workspace_id, name, json)
@@ -30,6 +33,23 @@ pub fn run(ctx: &CliContext, args: EnvironmentArgs) -> i32 {
     }
 }
 
+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: &str) -> CommandResult {
     let environments = ctx
         .db()

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

@@ -1,5 +1,6 @@
 use crate::cli::{GenerateArgs, PluginArgs, PluginCommands, PluginPathArg};
 use crate::ui;
+use crate::utils::http;
 use keyring::Entry;
 use rand::Rng;
 use rolldown::{
@@ -7,7 +8,6 @@ use rolldown::{
     WatchOption, Watcher,
 };
 use serde::Deserialize;
-use serde_json::Value;
 use std::collections::HashSet;
 use std::fs;
 use std::io::{self, IsTerminal, Read, Write};
@@ -186,10 +186,8 @@ async fn publish(args: PluginPathArg) -> CommandResult {
 
     ui::info("Uploading plugin");
     let url = format!("{}/api/v1/plugins/publish", environment.api_base_url());
-    let response = reqwest::Client::new()
+    let response = http::build_client(Some(&token))?
         .post(url)
-        .header("X-Yaak-Session", token)
-        .header(reqwest::header::USER_AGENT, user_agent())
         .header(reqwest::header::CONTENT_TYPE, "application/zip")
         .body(archive)
         .send()
@@ -201,7 +199,7 @@ async fn publish(args: PluginPathArg) -> CommandResult {
         response.text().await.map_err(|e| format!("Failed reading publish response body: {e}"))?;
 
     if !status.is_success() {
-        return Err(parse_api_error(status.as_u16(), &body));
+        return Err(http::parse_api_error(status.as_u16(), &body));
     }
 
     let published: PublishResponse = serde_json::from_str(&body)
@@ -389,32 +387,6 @@ fn get_auth_token(environment: Environment) -> CommandResult<Option<String>> {
     }
 }
 
-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/{} ({})", env!("CARGO_PKG_VERSION"), ua_platform())
-}
-
-fn ua_platform() -> &'static str {
-    match std::env::consts::OS {
-        "windows" => "Win",
-        "darwin" => "Mac",
-        "linux" => "Linux",
-        _ => "Unknown",
-    }
-}
-
 fn random_name() -> String {
     const ADJECTIVES: &[&str] = &[
         "young", "youthful", "yellow", "yielding", "yappy", "yawning", "yummy", "yucky", "yearly",

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

@@ -5,10 +5,13 @@ use crate::utils::json::{
     apply_merge_patch, is_json_shorthand, parse_optional_json, parse_required_json, require_id,
     validate_create_id,
 };
+use crate::utils::schema::append_agent_hints;
 use schemars::schema_for;
 use serde_json::{Map, Value, json};
 use std::collections::HashMap;
+use std::io::Write;
 use tokio::sync::mpsc;
+use yaak_http::sender::HttpResponseEvent as SenderHttpResponseEvent;
 use yaak::send::{SendHttpRequestByIdWithPluginsParams, send_http_request_by_id_with_plugins};
 use yaak_models::models::{GrpcRequest, HttpRequest, WebsocketRequest};
 use yaak_models::queries::any_request::AnyRequest;
@@ -35,8 +38,8 @@ pub async fn run(
                 }
             };
         }
-        RequestCommands::Schema { request_type } => {
-            return match schema(ctx, request_type).await {
+        RequestCommands::Schema { request_type, pretty } => {
+            return match schema(ctx, request_type, pretty).await {
                 Ok(()) => 0,
                 Err(error) => {
                     eprintln!("Error: {error}");
@@ -75,7 +78,7 @@ fn list(ctx: &CliContext, workspace_id: &str) -> CommandResult {
     Ok(())
 }
 
-async fn schema(ctx: &CliContext, request_type: RequestSchemaType) -> CommandResult {
+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}"))?,
@@ -85,16 +88,51 @@ async fn schema(ctx: &CliContext, request_type: RequestSchemaType) -> CommandRes
             .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 = serde_json::to_string_pretty(&schema)
-        .map_err(|e| format!("Failed to format schema JSON: {e}"))?;
+    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(())
 }
 
+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 without `:` (for example `id`, `commentId`).",
+        );
+    }
+}
+
+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,
@@ -434,14 +472,24 @@ async fn send_http_request_by_id(
 ) -> Result<(), String> {
     let plugin_context = PluginContext::new(None, Some(workspace_id.to_string()));
 
-    let (event_tx, mut event_rx) = mpsc::channel(100);
+    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 {
+            if verbose && !matches!(event, SenderHttpResponseEvent::ChunkReceived { .. }) {
                 println!("{}", event);
             }
         }
     });
+    let body_handle = tokio::task::spawn_blocking(move || {
+        let mut stdout = std::io::stdout();
+        while let Some(chunk) = body_chunk_rx.blocking_recv() {
+            if stdout.write_all(&chunk).is_err() {
+                break;
+            }
+            let _ = stdout.flush();
+        }
+    });
     let response_dir = ctx.data_dir().join("responses");
 
     let result = send_http_request_by_id_with_plugins(SendHttpRequestByIdWithPluginsParams {
@@ -453,6 +501,7 @@ async fn send_http_request_by_id(
         cookie_jar_id: None,
         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,
@@ -462,24 +511,7 @@ async fn send_http_request_by_id(
     .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);
+    let _ = body_handle.await;
+    result.map_err(|e| e.to_string())?;
     Ok(())
 }

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

@@ -4,6 +4,8 @@ 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;
 
@@ -12,6 +14,7 @@ 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),
@@ -27,6 +30,23 @@ pub fn run(ctx: &CliContext, args: WorkspaceArgs) -> i32 {
     }
 }
 
+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}"))?;

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

@@ -4,6 +4,7 @@ mod context;
 mod plugin_events;
 mod ui;
 mod utils;
+mod version;
 
 use clap::Parser;
 use cli::{Cli, Commands, RequestCommands};
@@ -11,10 +12,18 @@ use context::CliContext;
 
 #[tokio::main]
 async fn main() {
-    let Cli { data_dir, environment, verbose, command } = Cli::parse();
+    let Cli { data_dir, environment, verbose, log, command } = Cli::parse();
 
-    if verbose {
-        env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+    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" };

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

@@ -1,2 +1,4 @@
 pub mod confirm;
+pub mod http;
 pub mod json;
+pub mod schema;

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/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/tests/environment_commands.rs

@@ -78,3 +78,19 @@ fn json_create_and_update_merge_patch_round_trip() {
         .stdout(contains("\"name\": \"Json Environment\""))
         .stdout(contains("\"color\": \"#00ff00\""));
 }
+
+#[test]
+fn environment_schema_outputs_json_schema() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+
+    cli_cmd(data_dir)
+        .args(["environment", "schema"])
+        .assert()
+        .success()
+        .stdout(contains("\"type\":\"object\""))
+        .stdout(contains("\"x-yaak-agent-hints\""))
+        .stdout(contains("\"templateVariableSyntax\":\"${[ my_var ]}\""))
+        .stdout(contains("\"templateFunctionSyntax\":\"${[ namespace.my_func(a='aaa',b='bbb') ]}\""))
+        .stdout(contains("\"workspaceId\""));
+}

crates-cli/yaak-cli/tests/request_commands.rs

@@ -156,7 +156,6 @@ fn request_send_persists_response_body_and_events() {
         .args(["request", "send", &request_id])
         .assert()
         .success()
-        .stdout(contains("HTTP 200 OK"))
         .stdout(contains("hello from integration test"));
 
     let qm = query_manager(data_dir);
@@ -189,6 +188,24 @@ fn request_schema_http_outputs_json_schema() {
         .args(["request", "schema", "http"])
         .assert()
         .success()
+        .stdout(contains("\"type\":\"object\""))
+        .stdout(contains("\"x-yaak-agent-hints\""))
+        .stdout(contains("\"templateVariableSyntax\":\"${[ my_var ]}\""))
+        .stdout(contains("\"templateFunctionSyntax\":\"${[ namespace.my_func(a='aaa',b='bbb') ]}\""))
+        .stdout(contains("\"authentication\":"))
+        .stdout(contains("/foo/:id/comments/:commentId"))
+        .stdout(contains("put concrete values in `urlParameters`"));
+}
+
+#[test]
+fn request_schema_http_pretty_prints_with_flag() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+
+    cli_cmd(data_dir)
+        .args(["request", "schema", "http", "--pretty"])
+        .assert()
+        .success()
         .stdout(contains("\"type\": \"object\""))
         .stdout(contains("\"authentication\""));
 }

crates-cli/yaak-cli/tests/send_commands.rs

@@ -31,7 +31,6 @@ fn top_level_send_workspace_sends_http_requests_and_prints_summary() {
         .args(["send", "wk_test"])
         .assert()
         .success()
-        .stdout(contains("HTTP 200 OK"))
         .stdout(contains("workspace bulk send"))
         .stdout(contains("Send summary: 1 succeeded, 0 failed"));
 }
@@ -62,7 +61,6 @@ fn top_level_send_folder_sends_http_requests_and_prints_summary() {
         .args(["send", "fl_test"])
         .assert()
         .success()
-        .stdout(contains("HTTP 200 OK"))
         .stdout(contains("folder bulk send"))
         .stdout(contains("Send summary: 1 succeeded, 0 failed"));
 }

crates-cli/yaak-cli/tests/workspace_commands.rs

@@ -57,3 +57,19 @@ fn json_create_and_update_merge_patch_round_trip() {
         .stdout(contains("\"name\": \"Json Workspace\""))
         .stdout(contains("\"description\": \"Updated via JSON\""));
 }
+
+#[test]
+fn workspace_schema_outputs_json_schema() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+
+    cli_cmd(data_dir)
+        .args(["workspace", "schema"])
+        .assert()
+        .success()
+        .stdout(contains("\"type\":\"object\""))
+        .stdout(contains("\"x-yaak-agent-hints\""))
+        .stdout(contains("\"templateVariableSyntax\":\"${[ my_var ]}\""))
+        .stdout(contains("\"templateFunctionSyntax\":\"${[ namespace.my_func(a='aaa',b='bbb') ]}\""))
+        .stdout(contains("\"name\""));
+}

crates-tauri/yaak-app/src/http_request.rs

@@ -154,6 +154,7 @@ async fn send_http_request_inner<R: Runtime>(
         cookie_jar_id,
         response_dir: &response_dir,
         emit_events_to: None,
+        emit_response_body_chunks_to: None,
         existing_response: Some(response_ctx.response().clone()),
         plugin_manager,
         encryption_manager,

crates/yaak-models/src/models.rs

@@ -74,7 +74,7 @@ pub struct ClientCertificate {
     pub enabled: bool,
 }
 
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, TS)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
 #[ts(export, export_to = "gen_models.ts")]
 pub struct DnsOverride {
@@ -293,7 +293,7 @@ impl UpsertModelInfo for Settings {
     }
 }
 
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, TS)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, JsonSchema, TS)]
 #[serde(default, rename_all = "camelCase")]
 #[ts(export, export_to = "gen_models.ts")]
 #[enum_def(table_name = "workspaces")]
@@ -590,7 +590,7 @@ impl UpsertModelInfo for CookieJar {
     }
 }
 
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, TS)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, JsonSchema, TS)]
 #[serde(default, rename_all = "camelCase")]
 #[ts(export, export_to = "gen_models.ts")]
 #[enum_def(table_name = "environments")]
@@ -611,6 +611,8 @@ pub struct Environment {
     pub base: bool,
     pub parent_model: String,
     pub parent_id: Option<String>,
+    /// Variables defined in this environment scope.
+    /// Child environments override parent variables by name.
     pub variables: Vec<EnvironmentVariable>,
     pub color: Option<String>,
     pub sort_priority: f64,
@@ -698,7 +700,7 @@ impl UpsertModelInfo for Environment {
     }
 }
 
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, TS)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, JsonSchema, TS)]
 #[serde(default, rename_all = "camelCase")]
 #[ts(export, export_to = "gen_models.ts")]
 pub struct EnvironmentVariable {
@@ -845,6 +847,8 @@ pub struct HttpUrlParameter {
     #[serde(default = "default_true")]
     #[ts(optional, as = "Option<bool>")]
     pub enabled: bool,
+    /// Colon-prefixed parameters are treated as path parameters if they match, like `/users/:id`
+    /// Other entries are appended as query parameters
     pub name: String,
     pub value: String,
     #[ts(optional, as = "Option<String>")]
@@ -877,6 +881,7 @@ pub struct HttpRequest {
     pub name: String,
     pub sort_priority: f64,
     pub url: String,
+    /// URL parameters used for both path placeholders (`:id`) and query string entries.
     pub url_parameters: Vec<HttpUrlParameter>,
 }
 
@@ -1118,6 +1123,7 @@ pub struct WebsocketRequest {
     pub name: String,
     pub sort_priority: f64,
     pub url: String,
+    /// URL parameters used for both path placeholders (`:id`) and query string entries.
     pub url_parameters: Vec<HttpUrlParameter>,
 }
 
@@ -1728,6 +1734,7 @@ pub struct GrpcRequest {
     pub name: String,
     pub service: Option<String>,
     pub sort_priority: f64,
+    /// Server URL (http for plaintext or https for secure)
     pub url: String,
 }
 

crates/yaak/src/send.rs

@@ -239,6 +239,7 @@ pub struct SendHttpRequestByIdParams<'a, T: TemplateCallback> {
     pub cookie_jar_id: Option<String>,
     pub response_dir: &'a Path,
     pub emit_events_to: Option<mpsc::Sender<SenderHttpResponseEvent>>,
+    pub emit_response_body_chunks_to: Option<mpsc::UnboundedSender<Vec<u8>>>,
     pub cancelled_rx: Option<watch::Receiver<bool>>,
     pub prepare_sendable_request: Option<&'a dyn PrepareSendableRequest>,
     pub executor: Option<&'a dyn SendRequestExecutor>,
@@ -255,6 +256,7 @@ pub struct SendHttpRequestParams<'a, T: TemplateCallback> {
     pub cookie_jar_id: Option<String>,
     pub response_dir: &'a Path,
     pub emit_events_to: Option<mpsc::Sender<SenderHttpResponseEvent>>,
+    pub emit_response_body_chunks_to: Option<mpsc::UnboundedSender<Vec<u8>>>,
     pub cancelled_rx: Option<watch::Receiver<bool>>,
     pub auth_context_id: Option<String>,
     pub existing_response: Option<HttpResponse>,
@@ -271,6 +273,7 @@ pub struct SendHttpRequestWithPluginsParams<'a> {
     pub cookie_jar_id: Option<String>,
     pub response_dir: &'a Path,
     pub emit_events_to: Option<mpsc::Sender<SenderHttpResponseEvent>>,
+    pub emit_response_body_chunks_to: Option<mpsc::UnboundedSender<Vec<u8>>>,
     pub existing_response: Option<HttpResponse>,
     pub plugin_manager: Arc<PluginManager>,
     pub encryption_manager: Arc<EncryptionManager>,
@@ -288,6 +291,7 @@ pub struct SendHttpRequestByIdWithPluginsParams<'a> {
     pub cookie_jar_id: Option<String>,
     pub response_dir: &'a Path,
     pub emit_events_to: Option<mpsc::Sender<SenderHttpResponseEvent>>,
+    pub emit_response_body_chunks_to: Option<mpsc::UnboundedSender<Vec<u8>>>,
     pub plugin_manager: Arc<PluginManager>,
     pub encryption_manager: Arc<EncryptionManager>,
     pub plugin_context: &'a PluginContext,
@@ -353,6 +357,7 @@ pub async fn send_http_request_by_id_with_plugins(
         cookie_jar_id: params.cookie_jar_id,
         response_dir: params.response_dir,
         emit_events_to: params.emit_events_to,
+        emit_response_body_chunks_to: params.emit_response_body_chunks_to,
         existing_response: None,
         plugin_manager: params.plugin_manager,
         encryption_manager: params.encryption_manager,
@@ -397,6 +402,7 @@ pub async fn send_http_request_with_plugins(
         cookie_jar_id: params.cookie_jar_id,
         response_dir: params.response_dir,
         emit_events_to: params.emit_events_to,
+        emit_response_body_chunks_to: params.emit_response_body_chunks_to,
         cancelled_rx: params.cancelled_rx,
         auth_context_id: None,
         existing_response: params.existing_response,
@@ -427,6 +433,7 @@ pub async fn send_http_request_by_id<T: TemplateCallback>(
         cookie_jar_id: params.cookie_jar_id,
         response_dir: params.response_dir,
         emit_events_to: params.emit_events_to,
+        emit_response_body_chunks_to: params.emit_response_body_chunks_to,
         cancelled_rx: params.cancelled_rx,
         existing_response: None,
         prepare_sendable_request: params.prepare_sendable_request,
@@ -687,13 +694,17 @@ pub async fn send_http_request<T: TemplateCallback>(
             Ok(n) => {
                 written_bytes += n;
                 let start_idx = response_body.len() - n;
-                file.write_all(&response_body[start_idx..]).await.map_err(|source| {
+                let chunk = &response_body[start_idx..];
+                file.write_all(chunk).await.map_err(|source| {
                     SendHttpRequestError::WriteResponseBody { path: body_path.clone(), source }
                 })?;
                 file.flush().await.map_err(|source| SendHttpRequestError::WriteResponseBody {
                     path: body_path.clone(),
                     source,
                 })?;
+                if let Some(tx) = params.emit_response_body_chunks_to.as_ref() {
+                    let _ = tx.send(chunk.to_vec());
+                }
 
                 let now = Instant::now();
                 let should_update = now.duration_since(last_progress_update).as_millis()