cli: prep 0.4.0 stable release

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

@@ -33,12 +33,11 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Install wasm-pack
-        run: npm run bootstrap:install-wasm-pack
-
       - name: Build plugin assets
+        env:
+          SKIP_WASM_BUILD: "1"
         run: |
-          npm run build-plugins
+          npm run build
           npm run vendor:vendor-plugins
 
       - name: Upload vendored assets
@@ -110,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 }}
 

README.md

@@ -22,7 +22,7 @@
   <!-- sponsors-premium --><a href="https://github.com/MVST-Solutions"><img src="https:&#x2F;&#x2F;github.com&#x2F;MVST-Solutions.png" width="80px" alt="User avatar: MVST-Solutions" /></a>&nbsp;&nbsp;<a href="https://github.com/dharsanb"><img src="https:&#x2F;&#x2F;github.com&#x2F;dharsanb.png" width="80px" alt="User avatar: dharsanb" /></a>&nbsp;&nbsp;<a href="https://github.com/railwayapp"><img src="https:&#x2F;&#x2F;github.com&#x2F;railwayapp.png" width="80px" alt="User avatar: railwayapp" /></a>&nbsp;&nbsp;<a href="https://github.com/caseyamcl"><img src="https:&#x2F;&#x2F;github.com&#x2F;caseyamcl.png" width="80px" alt="User avatar: caseyamcl" /></a>&nbsp;&nbsp;<a href="https://github.com/bytebase"><img src="https:&#x2F;&#x2F;github.com&#x2F;bytebase.png" width="80px" alt="User avatar: bytebase" /></a>&nbsp;&nbsp;<a href="https://github.com/"><img src="https:&#x2F;&#x2F;raw.githubusercontent.com&#x2F;JamesIves&#x2F;github-sponsors-readme-action&#x2F;dev&#x2F;.github&#x2F;assets&#x2F;placeholder.png" width="80px" alt="User avatar: " /></a>&nbsp;&nbsp;<!-- sponsors-premium -->
 </p>
 <p align="center">
-  <!-- sponsors-base --><a href="https://github.com/seanwash"><img src="https:&#x2F;&#x2F;github.com&#x2F;seanwash.png" width="50px" alt="User avatar: seanwash" /></a>&nbsp;&nbsp;<a href="https://github.com/jerath"><img src="https:&#x2F;&#x2F;github.com&#x2F;jerath.png" width="50px" alt="User avatar: jerath" /></a>&nbsp;&nbsp;<a href="https://github.com/itsa-sh"><img src="https:&#x2F;&#x2F;github.com&#x2F;itsa-sh.png" width="50px" alt="User avatar: itsa-sh" /></a>&nbsp;&nbsp;<a href="https://github.com/dmmulroy"><img src="https:&#x2F;&#x2F;github.com&#x2F;dmmulroy.png" width="50px" alt="User avatar: dmmulroy" /></a>&nbsp;&nbsp;<a href="https://github.com/timcole"><img src="https:&#x2F;&#x2F;github.com&#x2F;timcole.png" width="50px" alt="User avatar: timcole" /></a>&nbsp;&nbsp;<a href="https://github.com/VLZH"><img src="https:&#x2F;&#x2F;github.com&#x2F;VLZH.png" width="50px" alt="User avatar: VLZH" /></a>&nbsp;&nbsp;<a href="https://github.com/terasaka2k"><img src="https:&#x2F;&#x2F;github.com&#x2F;terasaka2k.png" width="50px" alt="User avatar: terasaka2k" /></a>&nbsp;&nbsp;<a href="https://github.com/andriyor"><img src="https:&#x2F;&#x2F;github.com&#x2F;andriyor.png" width="50px" alt="User avatar: andriyor" /></a>&nbsp;&nbsp;<a href="https://github.com/majudhu"><img src="https:&#x2F;&#x2F;github.com&#x2F;majudhu.png" width="50px" alt="User avatar: majudhu" /></a>&nbsp;&nbsp;<a href="https://github.com/axelrindle"><img src="https:&#x2F;&#x2F;github.com&#x2F;axelrindle.png" width="50px" alt="User avatar: axelrindle" /></a>&nbsp;&nbsp;<a href="https://github.com/jirizverina"><img src="https:&#x2F;&#x2F;github.com&#x2F;jirizverina.png" width="50px" alt="User avatar: jirizverina" /></a>&nbsp;&nbsp;<a href="https://github.com/chip-well"><img src="https:&#x2F;&#x2F;github.com&#x2F;chip-well.png" width="50px" alt="User avatar: chip-well" /></a>&nbsp;&nbsp;<a href="https://github.com/GRAYAH"><img src="https:&#x2F;&#x2F;github.com&#x2F;GRAYAH.png" width="50px" alt="User avatar: GRAYAH" /></a>&nbsp;&nbsp;<a href="https://github.com/flashblaze"><img src="https:&#x2F;&#x2F;github.com&#x2F;flashblaze.png" width="50px" alt="User avatar: flashblaze" /></a>&nbsp;&nbsp;<!-- sponsors-base -->
+  <!-- sponsors-base --><a href="https://github.com/seanwash"><img src="https:&#x2F;&#x2F;github.com&#x2F;seanwash.png" width="50px" alt="User avatar: seanwash" /></a>&nbsp;&nbsp;<a href="https://github.com/jerath"><img src="https:&#x2F;&#x2F;github.com&#x2F;jerath.png" width="50px" alt="User avatar: jerath" /></a>&nbsp;&nbsp;<a href="https://github.com/itsa-sh"><img src="https:&#x2F;&#x2F;github.com&#x2F;itsa-sh.png" width="50px" alt="User avatar: itsa-sh" /></a>&nbsp;&nbsp;<a href="https://github.com/dmmulroy"><img src="https:&#x2F;&#x2F;github.com&#x2F;dmmulroy.png" width="50px" alt="User avatar: dmmulroy" /></a>&nbsp;&nbsp;<a href="https://github.com/timcole"><img src="https:&#x2F;&#x2F;github.com&#x2F;timcole.png" width="50px" alt="User avatar: timcole" /></a>&nbsp;&nbsp;<a href="https://github.com/VLZH"><img src="https:&#x2F;&#x2F;github.com&#x2F;VLZH.png" width="50px" alt="User avatar: VLZH" /></a>&nbsp;&nbsp;<a href="https://github.com/terasaka2k"><img src="https:&#x2F;&#x2F;github.com&#x2F;terasaka2k.png" width="50px" alt="User avatar: terasaka2k" /></a>&nbsp;&nbsp;<a href="https://github.com/andriyor"><img src="https:&#x2F;&#x2F;github.com&#x2F;andriyor.png" width="50px" alt="User avatar: andriyor" /></a>&nbsp;&nbsp;<a href="https://github.com/majudhu"><img src="https:&#x2F;&#x2F;github.com&#x2F;majudhu.png" width="50px" alt="User avatar: majudhu" /></a>&nbsp;&nbsp;<a href="https://github.com/axelrindle"><img src="https:&#x2F;&#x2F;github.com&#x2F;axelrindle.png" width="50px" alt="User avatar: axelrindle" /></a>&nbsp;&nbsp;<a href="https://github.com/jirizverina"><img src="https:&#x2F;&#x2F;github.com&#x2F;jirizverina.png" width="50px" alt="User avatar: jirizverina" /></a>&nbsp;&nbsp;<a href="https://github.com/chip-well"><img src="https:&#x2F;&#x2F;github.com&#x2F;chip-well.png" width="50px" alt="User avatar: chip-well" /></a>&nbsp;&nbsp;<a href="https://github.com/GRAYAH"><img src="https:&#x2F;&#x2F;github.com&#x2F;GRAYAH.png" width="50px" alt="User avatar: GRAYAH" /></a>&nbsp;&nbsp;<a href="https://github.com/flashblaze"><img src="https:&#x2F;&#x2F;github.com&#x2F;flashblaze.png" width="50px" alt="User avatar: flashblaze" /></a>&nbsp;&nbsp;<a href="https://github.com/Frostist"><img src="https:&#x2F;&#x2F;github.com&#x2F;Frostist.png" width="50px" alt="User avatar: Frostist" /></a>&nbsp;&nbsp;<!-- sponsors-base -->
 </p>
 
 ![Yaak API Client](https://yaak.app/static/screenshot.png)

crates-cli/yaak-cli/README.md

@@ -1,87 +1,66 @@
-# yaak-cli
+# Yaak CLI
 
-Command-line interface for Yaak.
+The `yaak` CLI for publishing plugins and creating/updating/sending requests. 
 
-## Command Overview
+## Installation
 
-Current top-level commands:
+```sh
+npm install @yaakapp/cli
+```
+
+## Agentic Workflows
+
+The `yaak` CLI is primarily meant to be used by AI agents, and has the following features:
+
+- `schema` subcommands to get the JSON Schema for any model (eg. `yaak request schema http`)
+- `--json '{...}'` input format to create and update data
+- `--verbose` mode for extracting debug info while sending requests
+- The ability to send entire workspaces and folders (Supports `--parallel` and `--fail-fast`)
+
+### Example Prompts
+
+Use the `yaak` CLI with agents like Claude or Codex to do useful things for you.
+
+Here are some example prompts:
 
 ```text
-yaakcli send <request_id>
-yaakcli workspace list
-yaakcli workspace show <workspace_id>
-yaakcli workspace create --name <name>
-yaakcli workspace create --json '{"name":"My Workspace"}'
-yaakcli workspace create '{"name":"My Workspace"}'
-yaakcli workspace update --json '{"id":"wk_abc","description":"Updated"}'
-yaakcli workspace delete <workspace_id> [--yes]
-yaakcli request list <workspace_id>
-yaakcli request show <request_id>
-yaakcli request send <request_id>
-yaakcli request create <workspace_id> --name <name> --url <url> [--method GET]
-yaakcli request create --json '{"workspaceId":"wk_abc","name":"Users","url":"https://api.example.com/users"}'
-yaakcli request create '{"workspaceId":"wk_abc","name":"Users","url":"https://api.example.com/users"}'
-yaakcli request update --json '{"id":"rq_abc","name":"Users v2"}'
-yaakcli request delete <request_id> [--yes]
-yaakcli folder list <workspace_id>
-yaakcli folder show <folder_id>
-yaakcli folder create <workspace_id> --name <name>
-yaakcli folder create --json '{"workspaceId":"wk_abc","name":"Auth"}'
-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 show <environment_id>
-yaakcli environment create <workspace_id> --name <name>
-yaakcli environment create --json '{"workspaceId":"wk_abc","name":"Production"}'
-yaakcli environment create '{"workspaceId":"wk_abc","name":"Production"}'
-yaakcli environment update --json '{"id":"ev_abc","color":"#00ff00"}'
-yaakcli environment delete <environment_id> [--yes]
+Scan my API routes and create a workspace (using yaak cli) with 
+all the requests needed for me to do manual testing?  
 ```
 
-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
-
-Notes:
-
-- `send` is currently a shortcut for sending an HTTP request ID.
-- `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.
-- `update` uses JSON Merge Patch semantics (RFC 7386) for partial updates.
-
-## Examples
-
-```bash
-yaakcli workspace list
-yaakcli workspace create --name "My Workspace"
-yaakcli workspace show wk_abc
-yaakcli workspace update --json '{"id":"wk_abc","description":"Team workspace"}'
-yaakcli request list wk_abc
-yaakcli request show rq_abc
-yaakcli request create wk_abc --name "Users" --url "https://api.example.com/users"
-yaakcli request update --json '{"id":"rq_abc","name":"Users v2"}'
-yaakcli request send rq_abc -e ev_abc
-yaakcli request delete rq_abc --yes
-yaakcli folder create wk_abc --name "Auth"
-yaakcli folder update --json '{"id":"fl_abc","name":"Auth v2"}'
-yaakcli environment create wk_abc --name "Production"
-yaakcli environment update --json '{"id":"ev_abc","color":"#00ff00"}'
+```text
+Send all the GraphQL requests in my workspace
 ```
 
-## Roadmap
+## Description
 
-Planned command expansion (request schema and polymorphic send) is tracked in `PLAN.md`.
+Here's the current print of `yaak --help`
 
-When command behavior changes, update this README and verify with:
+```text
+Yaak CLI - API client from the command line
 
-```bash
-cargo run -q -p yaak-cli -- --help
-cargo run -q -p yaak-cli -- request --help
-cargo run -q -p yaak-cli -- workspace --help
-cargo run -q -p yaak-cli -- folder --help
-cargo run -q -p yaak-cli -- environment --help
+Usage: yaak [OPTIONS] <COMMAND>
+
+Commands:
+  auth         Authentication commands
+  plugin       Plugin development and publishing commands
+  send         Send a request, folder, or workspace by ID
+  workspace    Workspace commands
+  request      Request commands
+  folder       Folder commands
+  environment  Environment commands
+
+Options:
+      --data-dir <DATA_DIR>        Use a custom data directory
+  -e, --environment <ENVIRONMENT>  Environment ID to use for variable substitution
+  -v, --verbose                    Enable verbose send output (events and streamed response body)
+      --log [<LEVEL>]              Enable CLI logging; optionally set level (error|warn|info|debug|trace) [possible values: error, warn, info, debug, trace]
+  -h, --help                       Print help
+  -V, --version                    Print version
+
+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)
 ```

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,
 }
@@ -57,12 +68,8 @@ pub struct SendArgs {
     /// Request, folder, or workspace ID
     pub id: String,
 
-    /// Execute requests sequentially (default)
-    #[arg(long, conflicts_with = "parallel")]
-    pub sequential: bool,
-
     /// Execute requests in parallel
-    #[arg(long, conflicts_with = "sequential")]
+    #[arg(long)]
     pub parallel: bool,
 
     /// Stop on first request failure when sending folders/workspaces
@@ -71,6 +78,7 @@ pub struct SendArgs {
 }
 
 #[derive(Args)]
+#[command(disable_help_subcommand = true)]
 pub struct WorkspaceArgs {
     #[command(subcommand)]
     pub command: WorkspaceCommands,
@@ -81,6 +89,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 +140,7 @@ pub enum WorkspaceCommands {
 }
 
 #[derive(Args)]
+#[command(disable_help_subcommand = true)]
 pub struct RequestArgs {
     #[command(subcommand)]
     pub command: RequestCommands,
@@ -154,6 +170,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 +227,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 +306,7 @@ pub enum FolderCommands {
 }
 
 #[derive(Args)]
+#[command(disable_help_subcommand = true)]
 pub struct EnvironmentArgs {
     #[command(subcommand)]
     pub command: EnvironmentCommands,
@@ -277,6 +320,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 +334,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"}'
+  4) yaak environment create <workspace_id> --json '{"name":"Production"}'
+"#)]
     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 +377,7 @@ pub enum EnvironmentCommands {
 }
 
 #[derive(Args)]
+#[command(disable_help_subcommand = true)]
 pub struct AuthArgs {
     #[command(subcommand)]
     pub command: AuthCommands,
@@ -338,6 +396,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

@@ -2,9 +2,11 @@ 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,
+    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 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,18 @@ 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()
@@ -63,17 +78,11 @@ fn create(
     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 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,
-        workspace_id.clone().filter(|v| is_json_shorthand(v)),
-        "environment create",
-    )?;
+    let payload = parse_optional_json(json, json_shorthand, "environment create")?;
 
     if let Some(payload) = payload {
         if name.is_some() {
@@ -83,10 +92,11 @@ fn create(
         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());
-        }
+        merge_workspace_id_arg(
+            workspace_id_arg.as_deref(),
+            &mut environment.workspace_id,
+            "environment create",
+        )?;
 
         if environment.parent_model.is_empty() {
             environment.parent_model = "environment".to_string();
@@ -101,7 +111,7 @@ fn create(
         return Ok(());
     }
 
-    let workspace_id = workspace_id.ok_or_else(|| {
+    let workspace_id = workspace_id_arg.ok_or_else(|| {
         "environment create requires workspace_id unless JSON payload is provided".to_string()
     })?;
     let name = name.ok_or_else(|| {

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

@@ -2,8 +2,8 @@ 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,
+    apply_merge_patch, is_json_shorthand, merge_workspace_id_arg, parse_optional_json,
+    parse_required_json, require_id, validate_create_id,
 };
 use yaak_models::models::Folder;
 use yaak_models::util::UpdateSource;
@@ -58,15 +58,11 @@ fn create(
     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 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,
-        workspace_id.clone().filter(|v| is_json_shorthand(v)),
-        "folder create",
-    )?;
+    let payload = parse_optional_json(json, json_shorthand, "folder create")?;
 
     if let Some(payload) = payload {
         if name.is_some() {
@@ -74,12 +70,13 @@ fn create(
         }
 
         validate_create_id(&payload, "folder")?;
-        let folder: Folder = serde_json::from_value(payload)
+        let mut 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());
-        }
+        merge_workspace_id_arg(
+            workspace_id_arg.as_deref(),
+            &mut folder.workspace_id,
+            "folder create",
+        )?;
 
         let created = ctx
             .db()
@@ -90,7 +87,7 @@ fn create(
         return Ok(());
     }
 
-    let workspace_id = workspace_id.ok_or_else(|| {
+    let workspace_id = workspace_id_arg.ok_or_else(|| {
         "folder create requires workspace_id unless JSON payload is provided".to_string()
     })?;
     let name = name.ok_or_else(|| {

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

@@ -2,14 +2,17 @@ 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, parse_optional_json, parse_required_json, require_id,
-    validate_create_id,
+    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 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;
@@ -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,
@@ -298,15 +336,11 @@ fn create(
     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 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,
-        workspace_id.clone().filter(|v| is_json_shorthand(v)),
-        "request create",
-    )?;
+    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() {
@@ -314,12 +348,13 @@ fn create(
         }
 
         validate_create_id(&payload, "request")?;
-        let request: HttpRequest = serde_json::from_value(payload)
+        let mut 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());
-        }
+        merge_workspace_id_arg(
+            workspace_id_arg.as_deref(),
+            &mut request.workspace_id,
+            "request create",
+        )?;
 
         let created = ctx
             .db()
@@ -330,7 +365,7 @@ fn create(
         return Ok(());
     }
 
-    let workspace_id = workspace_id.ok_or_else(|| {
+    let workspace_id = workspace_id_arg.ok_or_else(|| {
         "request create requires workspace_id unless JSON payload is provided".to_string()
     })?;
     let name = name.unwrap_or_default();
@@ -434,14 +469,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 +498,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 +508,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/json.rs

@@ -63,6 +63,30 @@ pub fn validate_create_id(payload: &Value, context: &str) -> JsonResult<()> {
     }
 }
 
+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,

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,69 @@ fn json_create_and_update_merge_patch_round_trip() {
         .stdout(contains("\"name\": \"Json Environment\""))
         .stdout(contains("\"color\": \"#00ff00\""));
 }
+
+#[test]
+fn create_merges_positional_workspace_id_into_json_payload() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+    seed_workspace(data_dir, "wk_test");
+
+    let create_assert = cli_cmd(data_dir)
+        .args([
+            "environment",
+            "create",
+            "wk_test",
+            "--json",
+            r#"{"name":"Merged Environment"}"#,
+        ])
+        .assert()
+        .success();
+    let environment_id = parse_created_id(&create_assert.get_output().stdout, "environment create");
+
+    cli_cmd(data_dir)
+        .args(["environment", "show", &environment_id])
+        .assert()
+        .success()
+        .stdout(contains("\"workspaceId\": \"wk_test\""))
+        .stdout(contains("\"name\": \"Merged Environment\""));
+}
+
+#[test]
+fn create_rejects_conflicting_workspace_ids_between_arg_and_json() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+    seed_workspace(data_dir, "wk_test");
+    seed_workspace(data_dir, "wk_other");
+
+    cli_cmd(data_dir)
+        .args([
+            "environment",
+            "create",
+            "wk_test",
+            "--json",
+            r#"{"workspaceId":"wk_other","name":"Mismatch"}"#,
+        ])
+        .assert()
+        .failure()
+        .stderr(contains(
+            "environment create got conflicting workspace_id values between positional arg and JSON payload",
+        ));
+}
+
+#[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/folder_commands.rs

@@ -72,3 +72,51 @@ fn json_create_and_update_merge_patch_round_trip() {
         .stdout(contains("\"name\": \"Json Folder\""))
         .stdout(contains("\"description\": \"Folder Description\""));
 }
+
+#[test]
+fn create_merges_positional_workspace_id_into_json_payload() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+    seed_workspace(data_dir, "wk_test");
+
+    let create_assert = cli_cmd(data_dir)
+        .args([
+            "folder",
+            "create",
+            "wk_test",
+            "--json",
+            r#"{"name":"Merged Folder"}"#,
+        ])
+        .assert()
+        .success();
+    let folder_id = parse_created_id(&create_assert.get_output().stdout, "folder create");
+
+    cli_cmd(data_dir)
+        .args(["folder", "show", &folder_id])
+        .assert()
+        .success()
+        .stdout(contains("\"workspaceId\": \"wk_test\""))
+        .stdout(contains("\"name\": \"Merged Folder\""));
+}
+
+#[test]
+fn create_rejects_conflicting_workspace_ids_between_arg_and_json() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+    seed_workspace(data_dir, "wk_test");
+    seed_workspace(data_dir, "wk_other");
+
+    cli_cmd(data_dir)
+        .args([
+            "folder",
+            "create",
+            "wk_test",
+            "--json",
+            r#"{"workspaceId":"wk_other","name":"Mismatch"}"#,
+        ])
+        .assert()
+        .failure()
+        .stderr(contains(
+            "folder create got conflicting workspace_id values between positional arg and JSON payload",
+        ));
+}

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

@@ -130,6 +130,54 @@ fn create_allows_workspace_only_with_empty_defaults() {
     assert_eq!(request.url, "");
 }
 
+#[test]
+fn create_merges_positional_workspace_id_into_json_payload() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+    seed_workspace(data_dir, "wk_test");
+
+    let create_assert = cli_cmd(data_dir)
+        .args([
+            "request",
+            "create",
+            "wk_test",
+            "--json",
+            r#"{"name":"Merged Request","url":"https://example.com"}"#,
+        ])
+        .assert()
+        .success();
+    let request_id = parse_created_id(&create_assert.get_output().stdout, "request create");
+
+    cli_cmd(data_dir)
+        .args(["request", "show", &request_id])
+        .assert()
+        .success()
+        .stdout(contains("\"workspaceId\": \"wk_test\""))
+        .stdout(contains("\"name\": \"Merged Request\""));
+}
+
+#[test]
+fn create_rejects_conflicting_workspace_ids_between_arg_and_json() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let data_dir = temp_dir.path();
+    seed_workspace(data_dir, "wk_test");
+    seed_workspace(data_dir, "wk_other");
+
+    cli_cmd(data_dir)
+        .args([
+            "request",
+            "create",
+            "wk_test",
+            "--json",
+            r#"{"workspaceId":"wk_other","name":"Mismatch"}"#,
+        ])
+        .assert()
+        .failure()
+        .stderr(contains(
+            "request create got conflicting workspace_id values between positional arg and JSON payload",
+        ));
+}
+
 #[test]
 fn request_send_persists_response_body_and_events() {
     let temp_dir = TempDir::new().expect("Failed to create temp dir");
@@ -156,7 +204,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 +236,26 @@ 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()

npm/README.md

@@ -1,7 +0,0 @@
-# Yaak CLI NPM Packages
-
-The Rust `yaak` CLI binary is published to NPM with a meta package (`@yaakapp/cli`) and
-platform-specific optional dependency packages. The package exposes both `yaak` and `yaakcli`
-commands for compatibility.
-
-This follows the same strategy previously used in the standalone `yaak-cli` repo.

npm/cli/prepublish.js

@@ -1,5 +1,5 @@
 const fs = require("node:fs");
 const path = require("node:path");
 
-const readme = path.join(__dirname, "..", "..", "README.md");
-fs.copyFileSync(readme, path.join(__dirname, "README.md"));
+const cliReadme = path.join(__dirname, "..", "..", "crates-cli", "yaak-cli", "README.md");
+fs.copyFileSync(cliReadme, path.join(__dirname, "README.md"));

package.json

@@ -70,7 +70,6 @@
     "app-dev": "node scripts/run-dev.mjs",
     "migration": "node scripts/create-migration.cjs",
     "build": "npm run --workspaces --if-present build",
-    "build-plugins": "npm run --workspaces --if-present build",
     "test": "npm run --workspaces --if-present test",
     "icons": "run-p icons:*",
     "icons:dev": "tauri icon crates-tauri/yaak-app/icons/icon-dev.png --output crates-tauri/yaak-app/icons/dev",