cli: prep 0.4.0 stable release

Author: gschier

crates-cli/yaak-cli/README.md

@@ -1,93 +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 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"}'
-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 schema [--pretty]
-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 send output (events and streamed response body)
-- `--log [level]`: enable CLI logging; optional level is `error|warn|info|debug|trace`
-
-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.
-- 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
-
-```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
+
+Here's the current print of `yaak --help`
+
+```text
+Yaak CLI - API client from the command line
+
+Usage: yaak [OPTIONS] <COMMAND>
 
-Planned command expansion (request schema and polymorphic send) is tracked in `PLAN.md`.
+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
 
-When command behavior changes, update this README and verify with:
+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
 
-```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
+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

@@ -68,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
@@ -342,8 +338,8 @@ pub enum EnvironmentCommands {
   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."#)]
+  4) yaak environment create <workspace_id> --json '{"name":"Production"}'
+"#)]
     Create {
         /// Workspace ID for flag-based mode, or positional JSON payload shorthand
         #[arg(value_name = "WORKSPACE_ID_OR_JSON")]

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

@@ -2,8 +2,8 @@ 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;
@@ -34,18 +34,13 @@ 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}"
-        ))?;
+    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}"))?;
+    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(())
 }
@@ -83,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() {
@@ -103,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();
@@ -121,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,28 +58,25 @@ 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() {
             return Err("folder create cannot combine --name with JSON payload".to_string());
         }
 
         validate_create_id(&payload, "folder")?;
-        let folder: Folder = serde_json::from_value(payload)
+        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/request.rs

@@ -2,17 +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_http::sender::HttpResponseEvent as SenderHttpResponseEvent;
 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;
@@ -336,28 +336,25 @@ 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() {
             return Err("request create cannot combine simple flags with JSON payload".to_string());
         }
 
         validate_create_id(&payload, "request")?;
-        let request: HttpRequest = serde_json::from_value(payload)
+        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()
@@ -368,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();