@deepraxis/cli 0.1.1-dev.926893 → 0.1.1-dev.a766ddd

package/README.md

@@ -19,11 +19,11 @@ The official command line for [知行云 Praxis](https://deepraxis.com), the clo
 ```sh
 npm install -g @deepraxis/cli
 praxis login
-praxis model chat completion create --model deepseek-flash \
+praxis api model chat completion create --model deepseek-flash \
   --data '{"messages":[{"role":"user","content":"Hello!"}]}'
 ```
 
-Every operation of the Praxis API is a command: about 350 of them across models, agents,
+Every operation of the Praxis API is a command under `praxis api`: about 350 of them across models, agents,
 sandboxes, cloud browsers, web search, databases, knowledge bases, files, media, automation
 and hosted applications. The command tree is generated from the same contract as the API and
 the SDK, so a new API capability reaches the CLI on the day it ships.
@@ -36,7 +36,7 @@ the SDK, so a new API capability reaches the CLI on the day it ships.
   AI coding agent runs it, and clean JSON in scripts. The CLI picks the mode by itself.
 - **Signs in through the browser.** `praxis login` approves the session in your browser and
   keeps the credential in the system keychain, never in a dotfile when a keychain exists.
-- **Predictable grammar.** `praxis <domain> <resource> <verb> [id]`, the same shape everywhere,
+- **Predictable grammar.** `praxis api <domain> <resource> <verb> [id]`, the same shape everywhere,
   with `--help` on every level.
 
 ## Install
@@ -68,7 +68,7 @@ Belong to several organizations? Every call runs in the active one:
 ```sh
 praxis org list
 praxis org switch <organization_id>
-praxis model list --org <organization_id>   # just this call
+praxis api model list --org <organization_id>   # just this call
 ```
 
 For CI and other headless environments, create an API key in the
@@ -84,12 +84,12 @@ export PRAXIS_API_KEY=<your-api-key>
 ### Models
 
 ```sh
-praxis model list
-praxis model chat completion create --model deepseek-flash \
+praxis api model list
+praxis api model chat completion create --model deepseek-flash \
   --data '{"messages":[{"role":"user","content":"A haiku"}]}'
-praxis model embedding create --model <embedding_model> \
+praxis api model embedding create --model <embedding_model> \
   --data '{"input":"hello world"}'
-praxis model image generation create --model <image_model> \
+praxis api model image generation create --model <image_model> \
   --prompt "a lighthouse at dawn"
 ```
 
@@ -98,53 +98,56 @@ praxis model image generation create --model <image_model> \
 Define an agent once, then talk to it in sessions:
 
 ```sh
-praxis agent create --data '{
+praxis api agent create --data '{
   "name": "helper",
   "model": {"id": "deepseek-flash"},
   "tools": [{"type": "agent_toolset_20260401"}]
 }'
-praxis agent session create --data '{"agent": "<agent_id>"}'
-praxis agent session event send <session_id> --data '{
+praxis api agent session create --data '{"agent": "<agent_id>"}'
+praxis api agent session event send <session_id> --data '{
   "events": [{
     "type": "user.message",
     "content": [{"type": "text", "text": "What can you do?"}]
   }]
 }'
-praxis agent session event stream --session <session_id>
+praxis api agent session event stream --session <session_id>
 ```
 
 ### Sandboxes
 
 ```sh
-praxis sandbox create --template-id base
-praxis sandbox command run <sandbox_id> \
+praxis api sandbox create --template-id base
+praxis api sandbox command run <sandbox_id> \
   --cmd "python3 -c 'print(6 * 7)'"
-praxis sandbox delete <sandbox_id> --yes
+praxis api sandbox delete <sandbox_id> --yes
 ```
 
 ### Search, data and automation
 
 ```sh
-praxis search create --query "AI agent frameworks" --max-results 5
-praxis database create --name notes
-praxis automation run create --data '{
+praxis api search create --query "AI agent frameworks" --max-results 5
+praxis api database create --name notes
+praxis api automation run create --data '{
   "source": "export default async (i) => ({ answer: i.n + 1 })",
   "language": "ts", "input": {"n": 41}, "wait": 30
 }'
 ```
 
-Browse everything with `praxis --help`, `praxis <domain> --help`, or the full
+Browse everything with `praxis --help`, `praxis api --help`, `praxis api <domain> --help`, or the full
 [command reference](https://unpkg.com/@deepraxis/cli/COMMANDS.md) that ships in the package.
 
 ## How commands work
 
+There are two layers. Top-level commands are workflows and session commands (`login`, `logout`,
+`whoami`, `org`, `skill`). Every API operation lives under `praxis api`, so the two never collide.
+
 ```text
-praxis  sandbox  command  run  sbx_123  --cmd "ls"  --json
-        domain   resource verb target   options     global
+praxis api  sandbox  command  run  sbx_123  --cmd "ls"  --json
+            domain   resource verb target   options     global
 ```
 
 - **One target, positionally.** The object a command acts on comes right after the verb. Parent
-  objects are options: `praxis database table list --database <database_id>`.
+  objects are options: `praxis api database table list --database <database_id>`.
 - **Request bodies.** Simple fields have their own options. Anything else goes in `--data`, as
   inline JSON, a file (`--data @body.json`) or stdin (`--data -`). Field options win over the
   same field in `--data`.
@@ -152,7 +155,7 @@ praxis  sandbox  command  run  sbx_123  --cmd "ls"  --json
   resumes from a page you saved.
 - **Safety.** Deleting and other destructive commands ask for confirmation, or need `--yes`
   when no one can answer, for example in a script.
-- **Escape hatch.** `praxis api <METHOD> <path> [--data …]` calls any endpoint with your
+- **Escape hatch.** `praxis api <METHOD> <path> [--data …]` (an uppercase method, such as `praxis api GET /model/v1/models`) calls any endpoint with your
   current credential, including ones that are new since your installed version.
 
 ## Output for people, AI agents and scripts
@@ -167,7 +170,7 @@ Errors follow the same rule. In JSON they are one object on stderr with `code`,
 `hint`, `status` and `request_id`, so a script or an agent can tell a typo from a quota limit.
 
 ```sh
-praxis model list --json | jq -r '.data[].id'
+praxis api model list --json | jq -r '.data[].id'
 ```
 
 ## Teach your AI agent to use Praxis

package/dist/praxis.js

@@ -1973,7 +1973,7 @@ clears to null; an empty string is stored as an empty string.`
     resource: "agent.sessions",
     method: "create",
     summary: "Create session",
-    description: `Create a session: one conversation with an agent. Pass agent as an agent id or {type:"agent", id, version?}; an id alone, or an object without version, pins the agent's active_version (the version chosen with agents.versions.apply, not necessarily the newest saved one). Unlike Anthropic Managed Agents, omit environment_id to use the default environment saved in the agent version (light for a new agent), unless computer_id (explicit, or the agent's default) selects a Computer; pass an environment id for a sandbox recipe. For service agents, explicit null allocates no machine, so codemode, bash and other machine tools are unavailable. Optional model must be one of the agent's allowed models; optional thinking is {effort: low|medium|high|xhigh|max|none} or null, where null inherits the agent default and then the model default (none requires the model to allow disabling thinking). Selections are saved before initial_events run; invalid ones return 400 invalid_request_error. Unlike Anthropic Managed Agents, the only inline agent override is system ({type:"agent_with_overrides", id, system}); to change the model, tools, MCP servers or skills, save a version instead. Supports vault_ids, up to 50, owned by the current organization and not archived; credential injection is deferred to a later version. budget is {type:"limit", max_list_cost:{amount, currency:"USD"}} where amount is a positive integer string of US cents ("2000" is USD 20.00); omitted budget defaults to "2000" and null removes the limit. Up to 500 file resources can be attached. Use initial_events to send a first user.message in this request, or send messages afterwards with sessions.events.send. The returned status can still be idle before initial events run; read agent.message and the subsequent session.status_idle event to confirm completion.`,
+    description: `Create a session: one conversation with an agent. Pass agent as an agent id or {type:"agent", id, version?}; an id alone, or an object without version, pins the agent's active_version (the version chosen with agents.versions.apply, not necessarily the newest saved one). Unlike Anthropic Managed Agents, omit environment_id to use the default environment saved in the agent version (light for a new agent), unless computer_id (explicit, or the agent's default) selects a Computer; pass an environment id for a sandbox recipe. For service agents, explicit null allocates no machine, so codemode, bash and other machine tools are unavailable. Optional model must be one of the agent's allowed models; optional thinking is {effort: low|medium|high|xhigh|max|none} or null, where null inherits the agent default and then the model default (none requires the model to allow disabling thinking). Selections are saved before initial_events run; invalid ones return 400 invalid_request_error. Unlike Anthropic Managed Agents, the only inline agent override is system ({type:"agent_with_overrides", id, system}); to change the model, tools, MCP servers or skills, save a version instead. Supports vault_ids, up to 50, owned by the current organization and not archived; credential injection is deferred to a later version. budget is {type:"limit", max_list_cost:{amount, currency:"USD"}} where amount is a positive decimal string of US dollars with at most 2 decimal places ("20.00" is USD 20.00); omitted budget defaults to "20.00" and null removes the limit. Up to 500 file resources can be attached. Use initial_events to send a first user.message in this request, or send messages afterwards with sessions.events.send. The returned status can still be idle before initial events run; read agent.message and the subsequent session.status_idle event to confirm completion.`,
     http: "POST",
     path: "/agent/v1/sessions",
     streaming: "no",
@@ -2549,9 +2549,9 @@ Available only on /agent/v1. Use the message_id field from own-face events, not
     query: [
       {
         name: "limit",
-        type: "number",
+        type: "integer",
         required: false,
-        description: "Number of items per page."
+        description: "Number of resources per page, from 1 to 100; defaults to 100."
       },
       {
         name: "page",
@@ -9610,7 +9610,8 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
         {
           name: "file_id",
           type: "string",
-          required: true
+          required: true,
+          description: "File ID to copy into this library; passed as the upload source instead of file bytes."
         },
         {
           name: "public_id",
@@ -25061,7 +25062,7 @@ async function publish(client2, input) {
   const timeout = input.timeout_ms ?? 120000;
   if (!Number.isFinite(timeout) || timeout < 0)
     throw new RangeError("timeout_ms must be non-negative and finite");
-  const contentType = [
+  const moduleTypes = [
     "application/javascript+module",
     "text/javascript",
     "application/javascript",
@@ -25070,9 +25071,30 @@ async function publish(client2, input) {
     "application/wasm",
     "application/octet-stream",
     "application/x-python"
-  ].find((type) => type === (input.main?.content_type ?? "application/javascript+module"));
-  if (!contentType)
-    throw new PraxisError({ code: "INVALID_PARAMS", message: `Unsupported module content_type: ${input.main?.content_type}` });
+  ];
+  const moduleType = (type) => {
+    const found = moduleTypes.find((candidate) => candidate === (type ?? "application/javascript+module"));
+    if (!found)
+      throw new PraxisError({ code: "INVALID_PARAMS", message: `Unsupported module content_type: ${type}` });
+    return found;
+  };
+  if (input.main && input.modules)
+    throw new PraxisError({ code: "INVALID_PARAMS", message: "Pass either main or modules, not both" });
+  if (input.main_module !== undefined && !input.modules)
+    throw new PraxisError({ code: "INVALID_PARAMS", message: "main_module requires modules; with main the entry is main.name" });
+  if (input.modules && input.modules.length === 0)
+    throw new PraxisError({ code: "INVALID_PARAMS", message: "modules must not be empty" });
+  const entryModules = input.main ? [{ name: input.main.name, content_type: moduleType(input.main.content_type), content_base64: base64(new TextEncoder().encode(input.main.content)) }] : input.modules?.map((module) => ({
+    name: module.name,
+    content_type: moduleType(module.content_type),
+    content_base64: base64(typeof module.content === "string" ? new TextEncoder().encode(module.content) : module.content)
+  }));
+  if (new Set(entryModules?.map((module) => module.name)).size !== (entryModules?.length ?? 0))
+    throw new PraxisError({ code: "INVALID_PARAMS", message: "Duplicate module name" });
+  const mainModule = input.main ? input.main.name : input.modules ? input.main_module ?? input.modules[0].name : undefined;
+  if (input.modules && !input.modules.some((module) => module.name === mainModule)) {
+    throw new PraxisError({ code: "INVALID_PARAMS", message: `main_module ${mainModule} is not among modules` });
+  }
   const files = Object.entries(input.files);
   if (files.length > 1e5)
     throw new PraxisError({ code: "LIMIT_EXCEEDED", message: "At most 100000 asset paths can be published" });
@@ -25125,7 +25147,7 @@ async function publish(client2, input) {
   const removed = Object.keys(previous).filter((key) => !Object.hasOwn(manifest, key));
   const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(manifest))));
   const manifestHash = Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
-  const staticOnly = !["main", "bindings", "compatibility_date", "compatibility_flags", "assets_config"].some((key) => Object.hasOwn(input, key));
+  const staticOnly = !["main", "modules", "main_module", "bindings", "compatibility_date", "compatibility_flags", "assets_config"].some((key) => Object.hasOwn(input, key));
   const unchanged = staticOnly && !!currentVersion && manifestHash === currentVersion.praxis.assets_manifest?.manifest_hash;
   const hashes = new Set(Object.values(manifest).map((entry) => entry.hash));
   const currentResult = {
@@ -25181,11 +25203,7 @@ async function publish(client2, input) {
     assets: versionAssets,
     ...input.compatibility_flags ? { compatibility_flags: input.compatibility_flags } : {},
     ...input.bindings ? { bindings: input.bindings } : {},
-    ...input.main ? { main_module: input.main.name, modules: [{
-      name: input.main.name,
-      content_type: contentType,
-      content_base64: base64(new TextEncoder().encode(input.main.content))
-    }] } : {}
+    ...entryModules ? { main_module: mainModule, modules: entryModules } : {}
   } });
   let deployment = result.deployment;
   if (!deployment)
@@ -25316,7 +25334,7 @@ function decideTabReuse(targetUrl, tabs) {
     if (best === undefined || rank < best.rank || rank === best.rank && (tab.active || !best.tab.active))
       best = { tab, rank };
   }
-  return best?.tab;
+  return best?.tab ?? tabs.find((tab) => isBlankTab(tab.url));
 }
 function buildConnectUrl(parts) {
   const url = new URL("/browser/v1/connect", parts.api);
@@ -25334,6 +25352,16 @@ function pickAgentContext(contexts, agentId) {
   return [...own].sort((x, y) => (x.createdAt ?? "").localeCompare(y.createdAt ?? "") || x.id.localeCompare(y.id))[0];
 }
 var agentContextName = (agentId) => `agent-${agentId}`.replace(/[^A-Za-z0-9._:-]/g, "-").slice(0, 128);
+function isBlankTab(value) {
+  if (value === "" || value === "about:blank")
+    return true;
+  try {
+    const url = new URL(value);
+    return (url.protocol === "https:" || url.protocol === "http:") && url.pathname === "/start" && (url.hostname.startsWith("console-") || url.hostname === "console.deepraxis.com");
+  } catch {
+    return false;
+  }
+}
 
 // ../../packages/sdk/typescript/src/helpers/browser-connect.ts
 var PLAYWRIGHT_CORE_VERSION = "1.63.0";
@@ -25519,10 +25547,11 @@ class Praxis {
       if (name === "database")
         Object.assign(resource, { count: (input) => count(transport, input) });
       if (name === "browser") {
+        const host = globalThis.process;
         Object.assign(resource, { connect: (options2) => connectBrowser({
           contexts: resource.contexts,
-          env: globalThis.process?.env ?? {},
-          builtin: globalThis.process?.getBuiltinModule?.bind(globalThis.process)
+          env: host?.env ?? {},
+          builtin: host?.getBuiltinModule?.bind(host)
         }, options2) });
       }
       if (name === "application")
@@ -25591,6 +25620,15 @@ function commandWords(resource, method) {
   const verb = kebab(method.replace(/^retrieve(?=[A-Z]|$)/, "get"));
   return [domain, ...resources, verb];
 }
+var API_WORD = "api";
+var HTTP_METHOD = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/;
+var domainOf = (command) => command.words[1];
+function movedTo(commands, words) {
+  if (!words.length || words[0] === API_WORD)
+    return;
+  const moved = [API_WORD, ...words];
+  return commands.some((c) => moved.every((w, i) => c.words[i] === w)) ? `praxis ${moved.join(" ")}` : undefined;
+}
 function commandTree(operations2) {
   const commands = [];
   const seen = new Set;
@@ -25606,7 +25644,7 @@ function commandTree(operations2) {
       if (["login", "logout", "whoami", "org", "api", "skill"].includes(words[0]))
         throw new Error(`Reserved command: ${key}`);
       seen.add(key);
-      commands.push({ words, op, ...method !== op.method ? { alias: method } : {} });
+      commands.push({ words: [API_WORD, ...words], op, ...method !== op.method ? { alias: method } : {} });
     }
   }
   for (const key of Object.keys(commandOverrides))
@@ -25902,24 +25940,68 @@ function help(commands, prefix, command) {
 `);
   }
   const matching = commands.filter((c) => prefix.every((w, i) => c.words[i] === w));
+  const global = [
+    "Global options:",
+    ...globalOptions.map((s) => `  ${describeOption(s)}`),
+    "  -h is an alias of --help",
+    "PRAXIS_ENV=develop|production (default: develop); no --env option.",
+    ""
+  ];
+  const sample = matching.find((c) => c.words.at(-1) === "list") ?? matching[0];
+  if (!prefix.length) {
+    const nouns = [...new Set(workflows.map((w) => w.words[0]))];
+    const summaries = new Map(workflows.map((w) => [w.words[0], w.words.length === 1 ? w.summary : undefined]));
+    const width = Math.max(...nouns.map((n) => n.length));
+    return [
+      "praxis <command> [options]",
+      "",
+      "Workflows:",
+      ...nouns.map((n) => `  ${n.padEnd(width)}  ${summaries.get(n) ?? workflows.filter((w) => w.words[0] === n).map((w) => w.words[1]).join(", ")}`),
+      "",
+      "API:",
+      `  praxis ${API_WORD} <domain> <resource> <action> [options]   one command per API operation`,
+      `  praxis ${API_WORD} <METHOD> <path> [--data JSON|@file|-]   raw request`,
+      `  Domains: ${domains(commands).join(", ")}`,
+      "",
+      ...global,
+      "Examples:",
+      `  ${sample ? example(sample) : "praxis --help"}`
+    ].join(`
+`);
+  }
   const children = [...new Set(matching.map((c) => c.words[prefix.length]).filter(Boolean))].sort();
-  if (!prefix.length)
-    children.unshift("login", "logout", "whoami", "org", "api", "skill");
+  const raw = prefix.length === 1 && prefix[0] === API_WORD;
   return [
     `praxis${prefix.length ? " " + prefix.join(" ") : ""} <command> [options]`,
     "",
+    ...raw ? ["Domains:"] : [],
     ...children.map((s) => `  ${s}`),
     "",
-    "Global options:",
-    ...globalOptions.map((s) => `  ${describeOption(s)}`),
-    "  -h is an alias of --help",
-    "PRAXIS_ENV=develop|production (default: develop); no --env option.",
-    "",
+    ...raw ? ["Raw request:", `  praxis ${API_WORD} <METHOD> <path> [--data JSON|@file|-]`, ""] : [],
+    ...global,
     "Examples:",
-    `  ${matching[0] ? example(matching.find((c) => c.words.at(-1) === "list") ?? matching[0]) : "praxis --help"}`
+    ...raw ? [`  praxis ${API_WORD} GET /model/v1/models`] : [],
+    `  ${sample ? example(sample) : "praxis --help"}`
   ].join(`
 `);
 }
+function domains(commands) {
+  return [...new Set(commands.map((c) => c.words[1]))].sort();
+}
+var workflows = [
+  { words: ["login"], usage: "login", summary: "Sign in with a browser device code." },
+  { words: ["logout"], usage: "logout", summary: "Remove the saved login from the keychain and fallback file." },
+  { words: ["whoami"], usage: "whoami", summary: "Show the signed-in identity and credential storage location." },
+  { words: ["org", "list"], usage: "org list", summary: "List organizations available to the login." },
+  { words: ["org", "switch"], usage: "org switch <organization_id>", summary: "Switch the login organization." },
+  { words: ["skill"], usage: "skill [--install <dir>]", summary: "Print the AI skill, or write <dir>/praxis-cli/SKILL.md." }
+];
+var workflowNouns = [...new Set(workflows.filter((w) => w.words.length > 1).map((w) => w.words[0]))];
+function nounHelp(noun) {
+  const mine = workflows.filter((w) => w.words[0] === noun);
+  return [...mine.map((w) => `praxis ${w.usage}`), "", "Examples:", `  praxis ${mine[0].usage}`].join(`
+`);
+}
 
 // src/config/env.ts
 var DEFAULT_ENV = "develop";
@@ -26286,7 +26368,7 @@ function commandSummary(command) {
     const chars = [...description];
     return chars.length > 120 ? chars.slice(0, 119).join("") + "…" : description;
   }
-  const words = [...command.words];
+  const words = command.words.slice(1);
   const verb = (words.pop() ?? "use").replace(/-/g, " ");
   if (verb === "list" && words.length && !words.at(-1).endsWith("s"))
     words[words.length - 1] += "s";
@@ -26312,21 +26394,17 @@ function skillDocument(commands) {
     "- Use `--limit N` to limit a server page for SDK-paginated commands. Other lists apply it only to displayed rows; `--param-limit` still sends the API parameter when available. `--all` follows supported pagination and cannot be combined with `--limit`.",
     "- Error JSON has an `error` object: `code` identifies the failure, `message` describes it, `hint` suggests recovery, `env` identifies the environment, `command` identifies the command, `status` is the HTTP status, and `request_id` correlates diagnostics. Unavailable fields are null. Exit codes: 0 success, 1 runtime/API error, 2 usage error.",
     "- Append `--help` to a command for its optional parameters. Required scalar body options below can also be supplied as fields in `--data`.",
+    "- Two layers: top-level commands (`login`, `org`, `skill`, …) are workflows and session commands; every API operation is under `praxis api <domain> …`. `praxis api <METHOD> <path>` sends a raw request (the method is uppercase).",
     "",
     "## Account and CLI",
     "",
-    "praxis login — Sign in with a browser device code.",
-    "praxis logout — Remove the saved login from the keychain and fallback file.",
-    "praxis whoami — Show the signed-in identity and credential storage location.",
-    "praxis org list — List organizations available to the login.",
-    "praxis org switch <organization_id> — Switch the login organization.",
-    "praxis api <METHOD> <path> — Call an API path directly. (--data for a request body)",
-    "praxis skill — Print this skill; use --install <dir> to write <dir>/praxis-cli/SKILL.md."
+    ...workflows.map((w) => `praxis ${w.usage} — ${w.summary.replace("Print the AI skill, or write", "Print this skill; use --install <dir> to write")}`),
+    "praxis api <METHOD> <path> — Call an API path directly. (--data for a request body)"
   ];
   let domain;
   for (const command of commands) {
-    if (command.words[0] !== domain) {
-      domain = command.words[0];
+    if (domainOf(command) !== domain) {
+      domain = domainOf(command);
       lines.push("", `## ${domain}`, "");
     }
     const target = targetParam(command.op);
@@ -27071,9 +27149,9 @@ function startProgress(ctx, write = (text) => writeOutput({ stderr: text })) {
 }
 
 // src/main.ts
-var version = "0.1.1-dev.0926893";
+var version = "0.1.1-dev.a766ddd";
 var commands = commandTree(operations);
-var manual = [["login"], ["logout"], ["whoami"], ["org", "list"], ["org", "switch"], ["api"], ["skill"]];
+var manual = [...workflows.map((w) => w.words), [API_WORD]];
 function route(argv) {
   const words = [], args = [];
   for (let i = 0;i < argv.length; i++) {
@@ -27089,7 +27167,11 @@ function route(argv) {
       continue;
     }
     words.push(arg);
+    if (words.length === 1 && words[0] === API_WORD && HTTP_METHOD.test(argv[i + 1] ?? ""))
+      return { words, args: [...args, ...argv.slice(i + 1)] };
     const command = commands.find((c) => c.words.length === words.length && c.words.every((w, n) => w === words[n]));
+    if (words.length === 1 && words[0] === API_WORD && argv[i + 1] !== undefined && !argv[i + 1].startsWith("-"))
+      continue;
     if (command || manual.some((c) => c.length === words.length && c.every((w, n) => w === words[n])))
       return { words, args: [...args, ...argv.slice(i + 1)], command };
   }
@@ -27162,7 +27244,7 @@ async function main(argv, injected = {}) {
     const selected = route(argv);
     ctx.command = commandLine(selected.words);
     ctx.resource = selected.words.at(-2) ?? selected.words[0];
-    const specs = [...globalOptions, ...selected.command ? [...operationOptions(selected.command.op), ...selected.command.op.body ? [dataOption] : []] : selected.words[0] === "api" ? [dataOption] : selected.words[0] === "skill" ? [{ name: "install", type: "string" }] : []];
+    const specs = [...globalOptions, ...selected.command ? [...operationOptions(selected.command.op), ...selected.command.op.body ? [dataOption] : []] : selected.words.join(" ") === API_WORD ? [dataOption] : selected.words[0] === "skill" ? [{ name: "install", type: "string" }] : []];
     const outputFlags = globalsOf(parseArgs(outputModeArgs(selected.args, specs), globalOptions));
     ctx.json = Boolean(outputFlags.json);
     Object.assign(ctx, decideOutputMode({ format: outputFlags.format, json: ctx.json, stdoutIsTTY: ports.stdoutIsTTY, env: ports.env }));
@@ -27176,15 +27258,22 @@ async function main(argv, injected = {}) {
       return 0;
     }
     if (!selected.words.length || !selected.command && !manual.some((c) => c.join(" ") === selected.words.join(" "))) {
-      if (selected.words.length && !commands.some((c) => selected.words.every((w, i) => c.words[i] === w)) && selected.words.join(" ") !== "org")
-        throw new UsageError(`Unknown command: ${selected.words.join(" ")}`);
+      if (selected.words.length && !commands.some((c) => selected.words.every((w, i) => c.words[i] === w)) && !workflowNouns.includes(selected.words.join(" "))) {
+        const moved = movedTo(commands, selected.words);
+        throw new UsageError(`Unknown command: ${selected.words.join(" ")}`, moved ? `Generated commands moved under \`praxis api\`. Did you mean: ${moved}?` : selected.words[0] === API_WORD ? "Run `praxis api --help` to list API domains." : "Run `praxis --help`.");
+      }
       if (parsed.positional.length)
         throw new UsageError("Unexpected arguments");
-      emit({ kind: "message", channel: "stdout", text: selected.words.join(" ") === "org" ? `praxis org list
-praxis org switch <organization_id>
-
-Examples:
-  praxis org list` : help(commands, selected.words) });
+      const noun = selected.words.join(" ");
+      emit({ kind: "message", channel: "stdout", text: workflowNouns.includes(noun) ? nounHelp(noun) : help(commands, selected.words) });
+      return 0;
+    }
+    if (selected.words.join(" ") === API_WORD && !parsed.positional.length && !flags.help) {
+      emit({ kind: "message", channel: "stdout", text: help(commands, [API_WORD]) });
+      return 0;
+    }
+    if (flags.help && selected.words.join(" ") === API_WORD && !parsed.positional.length) {
+      emit({ kind: "message", channel: "stdout", text: help(commands, [API_WORD]) });
       return 0;
     }
     if (flags.help && selected.words[0] === "skill") {
@@ -27318,7 +27407,9 @@ Examples:
         emit({ kind: "object", data: await auth.switchOrganization(parsed.positional[0]) });
         break;
       case "api": {
-        const method = parsed.positional[0].toUpperCase();
+        const method = parsed.positional[0];
+        if (!HTTP_METHOD.test(method))
+          throw new UsageError(`Unknown command: api ${method}`, "Run `praxis api --help` to list API domains; raw requests use an uppercase method, such as `praxis api GET /model/v1/models`.");
         await confirm(method.toLowerCase());
         if (!quiet) {
           stopProgress();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepraxis/cli",
-  "version": "0.1.1-dev.0926893",
+  "version": "0.1.1-dev.a766ddd",
   "type": "module",
   "bin": {
     "praxis": "dist/praxis.js"