metergraph-cli 0.1.0 → 0.2.0-preview.1

package/assets/skill/SKILL.md

@@ -12,22 +12,38 @@ Connection and troubleshooting: https://www.metergraph.dev/docs/guides/agent-acc
 
 Ask for or confirm these non-secret choices. Do not guess from the agent brand:
 
-1. Client: Claude Desktop, Claude Code, ChatGPT or Codex.
+1. Client: Claude Desktop, Claude Code, ChatGPT, Codex or Cursor.
 2. Execution runtime: customer machine or cloud. Codex local app/CLI/IDE is distinct from cloud execution. Claude Desktop remote connectors execute in Anthropic's cloud; Desktop local MCP is a separate mechanism. ChatGPT MCP apps execute in the cloud.
 3. Deployment: Metergraph hosted cloud, the signed commercial customer-local bundle, a customer-owned AWS installation (`byoc-core`), or the open-source self-hosted server. These have different addresses, accounts and credentials. Staging is not a customer setup path.
 4. Fresh workspace/installation or connecting an existing workspace. Ask for the intended workspace name and deployment origin, never a token.
 
 Use the routing below with those four choices. Follow the matching credential and client configuration instructions in the connection guide.
 
+For a first application trace, check the installed CLI's version and help before
+using it. `metergraph-cli@0.1.0` supports `doctor` and project skill
+installation; later versions may also offer `login`, `setup` and `verify`.
+Use those commands only if the installed package lists them. Use the [first
+trace guide](https://www.metergraph.dev/docs/start/first-trace/) for steps the
+package does not support. A CLI login or health probe alone does not prove
+application traffic. Verification needs an exact trace or request ID from an
+application invocation, its time window and the intended workspace.
+
 ## Route honestly
 
 | Client and runtime | Hosted | Customer-local bundle | Customer AWS | Open source self-hosted |
 | --- | --- | --- | --- | --- |
 | Claude Code or Codex on the customer machine | Keyed HTTP at `https://app.metergraph.dev/v1/agent/mcp` | Keyed HTTP at the installed local address, normally `http://127.0.0.1:8080/v1/agent/mcp` | Keyed HTTP at the customer's reachable installation address | Static `MG_AGENT_TOKENS` bearer at the OSS server address, normally `http://localhost:8787/v1/agent/mcp` |
+| Cursor on the customer machine | Project skill supported; MCP connection not validated in this guide | Project skill supported; MCP connection not validated in this guide | Project skill supported; MCP connection not validated in this guide | Project skill supported; MCP connection not validated in this guide |
 | Claude Desktop remote connector on an individual account | Custom connector with a scoped bearer key if Request headers are available for the account; verify tools before claiming success | Cannot reach localhost from Anthropic's cloud | Default private installation is unreachable from Anthropic's cloud; no validated public route in this guide | Cannot reach localhost from Anthropic's cloud |
 | Claude Desktop local MCP | Separate local extension required; not supported by this guide | Docker does not install a host extension | Separate local extension required; not supported by this guide | Docker does not install a host extension |
 | ChatGPT MCP app or cloud execution | Separate cloud client configuration; not supported by this guide | Cannot reach localhost | Default private installation is unreachable | Cannot reach localhost |
 
+For Cursor, the published CLI can install a project skill with
+`metergraph skill install --client cursor --runtime local` when installed.
+Confirm Cursor discovers the skill. This does not configure MCP or sign in.
+Use the first trace guide for instrumentation, and report the read connection
+as unverified until a supported Cursor MCP route is tested.
+
 For hosted Claude Desktop on an individual account, guide the human through Customize → Connectors → Add custom connector with `https://app.metergraph.dev/v1/agent/mcp`. They create a coding-agent key in the intended hosted workspace. If Request headers are available, choose No sign-in and enter a required header named `Authorization` with value `Bearer <key>` in the connector's private settings, never in chat. Request headers are in beta and may be unavailable for the account; do not claim the route works without them. They must enable the connector in a conversation. Team and Enterprise connectors may share fixed credentials across users, so do not put one person's workspace key in a shared connector. Do not present OAuth server code, a tool listing, local CLI installation or a saved configuration as connection success. Do not invent a released plugin, extension, tunnel or signup path. If a route is blocked, name the blocker and offer the customer-machine Claude Code/Codex keyed HTTP route or hosted deployment as appropriate. Do not expose localhost publicly or disable authentication as a workaround.
 
 For a fresh hosted workspace, first ask whether the human already has a Metergraph account and workspace. Direct them to https://app.metergraph.dev/ and the signup, invitation or sign-in flow actually offered. The hosted UI can offer "Get a free API key" for self-service signup, but do not assume that button or a workspace invitation is available to everyone. If access is unavailable, direct them to their workspace owner or Metergraph. Confirm the workspace before creating a coding-agent key.

package/assets/skill/manifest.json

@@ -3,7 +3,7 @@
   "name": "metergraph",
   "file": "SKILL.md",
   "source_url": "https://www.metergraph.dev/SKILL.md",
-  "sha256": "90f7d8d78a5b0b7a57436f194222f0c73310b0b04201c297c8fbf0b00ad6bb3f",
-  "size": 9149,
-  "revision": "sha256-90f7d8d78a5b"
+  "sha256": "57b920677adf62759c7221629327192a2d16b7e6034f7948ffd96cee402d4891",
+  "size": 10426,
+  "revision": "sha256-57b920677adf"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "metergraph-cli",
-  "version": "0.1.0",
-  "description": "Preview Metergraph command line tool with a read-only connection probe and a project skill installer",
+  "version": "0.2.0-preview.1",
+  "description": "Preview Metergraph command line tool with a read-only connection probe, a project skill installer, Metadata-only sign in and bounded workspace Metadata reads",
   "type": "module",
   "bin": {
     "metergraph": "bin/metergraph.js"

package/src/args.js

@@ -3,27 +3,96 @@ import {
   DEFAULT_TIMEOUT_MS,
   HANDOFF_SKILL_CLIENTS,
   HANDOFF_SKILL_RUNTIMES,
+  HANDOFF_LOGIN_RUNTIMES,
+  LOGIN_DEFAULT_TIMEOUT_MS,
+  LOGIN_MAX_TIMEOUT_MS,
+  LOGIN_MIN_TIMEOUT_MS,
+  LOGIN_RUNTIMES,
   MAX_TIMEOUT_MS,
   MIN_TIMEOUT_MS,
+  READ_DEFAULT_DAYS,
+  READ_DEFAULT_LIMIT,
+  READ_DEFAULT_TIMEOUT_MS,
+  READ_MAX_DAYS,
+  READ_MAX_LIMIT,
+  READ_MAX_TIMEOUT_MS,
+  READ_MIN_TIMEOUT_MS,
   SKILL_CLIENTS,
   SKILL_RUNTIMES,
+  TRACES_DEFAULT_LIMIT,
 } from "./constants.js";
 import { parseOrigin } from "./origin.js";
+import { isCursor, isSafeFilter } from "./read-contract.js";
 
-const COMMANDS = new Set(["doctor", "help", "skill"]);
-const HELP_TOPICS = new Set(["doctor", "skill"]);
+export const READ_COMMANDS = Object.freeze(["status", "context", "capabilities", "usage", "routes", "traces"]);
+const COMMANDS = new Set(["doctor", "help", "skill", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
+const HELP_TOPICS = new Set(["doctor", "skill", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
 const SKILL_ACTIONS = new Set(["install", "update"]);
+const READ_BASE = ["--project", "--config-dir", "--timeout-ms"];
 const OPTIONS = {
   doctor: new Set(["--url", "--timeout-ms"]),
   skill: new Set(["--client", "--runtime", "--project"]),
+  login: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--timeout-ms"]),
+  setup: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--env-file", "--client", "--timeout-ms", "--deployment", "--agent-token-file"]),
+  logout: new Set(["--project", "--config-dir"]),
+  status: new Set(READ_BASE),
+  context: new Set(READ_BASE),
+  capabilities: new Set(READ_BASE),
+  usage: new Set([...READ_BASE, "--days", "--limit"]),
+  routes: new Set([...READ_BASE, "--limit"]),
+  traces: new Set([...READ_BASE, "--days", "--limit", "--route", "--status", "--cursor"]),
+  verify: new Set([...READ_BASE, "--trace-id", "--request-id", "--since", "--until", "--source", "--days", "--poll-ms", "--max-attempts"]),
 };
+// Requests the read commands recognize and refuse, so a script gets an
+// explicit unsupported result instead of an unknown argument or, worse, a
+// broader query than it asked for. Nothing is sent for them.
+const REFUSED = {
+  "--environment": { value: true, reason: "environment_selector_unsupported" },
+  "--workload": { value: true, reason: "workload_filter_unsupported" },
+  "--since": { value: true, reason: "time_range_unsupported" },
+  "--until": { value: true, reason: "time_range_unsupported" },
+  "--sql": { value: true, reason: "query_unsupported" },
+  "--query": { value: true, reason: "query_unsupported" },
+  "--content": { value: false, reason: "content_access_unsupported" },
+  "--include-content": { value: false, reason: "content_access_unsupported" },
+  "--debug": { value: false, reason: "content_access_unsupported" },
+  "--replay": { value: false, reason: "content_access_unsupported" },
+};
+const REFUSED_MESSAGES = {
+  environment_selector_unsupported:
+    "--environment is not supported: the service's agent access contract has no environment selector, " +
+    "so the CLI never sends one. Results cover the bound workspace. No request was made.",
+  workload_filter_unsupported:
+    "--workload is not supported by this CLI version: it cannot verify from the returned traces that a " +
+    "workload filter was applied, so it never sends one. No request was made.",
+  time_range_unsupported:
+    "--since and --until are not supported. Use --days N (1 to 90) for a window relative to now. No request was made.",
+  query_unsupported:
+    "Free-form queries are not supported. Use the fixed options of this command. No request was made.",
+  content_access_unsupported:
+    "Read commands return Metadata only. They never read retained content, debug data or replays. No request was made.",
+};
+// Options that take no value.
+const FLAGS = {
+  login: new Set(["--signup", "--no-browser", "--reconnect"]),
+  setup: new Set(["--no-browser", "--repair", "--signup", "--reconnect", "--skip-skill", "--confirm-prerequisites"]),
+  verify: new Set(["--open", "--no-browser"]),
+};
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 // Parses argv into one of:
 //   { ok: true, command: "help", topic, json }
 //   { ok: true, command: "version", json }
 //   { ok: true, command: "doctor", origin, timeoutMs, json }
 //   { ok: true, command: "skill", action, client, runtime, project, json }
-//   { ok: false, command, json, code, message }
+//   { ok: true, command: "login", runtime, origin, workspace, project,
+//     configDir, timeoutMs, signup, noBrowser, reconnect, json }
+//   { ok: true, command: "logout", project, configDir, json }
+//   { ok: true, command: one of READ_COMMANDS, project, configDir, timeoutMs,
+//     days, limit, route, status, cursor, json }
+//   { ok: false, command, json, code, message, outcome }
+// outcome is invalid_input, or unsupported for a recognized request the read
+// commands refuse (such as --environment).
 // Error messages are fixed strings. They never contain an argument value,
 // because a mistyped argument can be a credential.
 export function parseArgs(argv) {
@@ -39,13 +108,15 @@ export function parseArgs(argv) {
   let topic = null;
   let version = false;
   const values = {};
+  const flags = new Set();
 
-  const fail = (code, message) => ({
+  const fail = (code, message, outcome = "invalid_input") => ({
     ok: false,
     command: command === "skill" && action !== null ? `skill ${action}` : command ?? (version ? "version" : null),
     json,
     code,
     message,
+    outcome,
   });
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -71,9 +142,24 @@ export function parseArgs(argv) {
       continue;
     }
 
-    if (command === "doctor" || command === "skill") {
+    if (READ_COMMANDS.includes(command)) {
+      const equals = arg.indexOf("=");
+      const name = equals === -1 ? arg : arg.slice(0, equals);
+      if (Object.hasOwn(REFUSED, name)) {
+        const { reason } = REFUSED[name];
+        return fail(reason, REFUSED_MESSAGES[reason], "unsupported");
+      }
+    }
+
+    if (Object.hasOwn(OPTIONS, command ?? "")) {
       const equals = arg.indexOf("=");
       const name = equals === -1 ? arg : arg.slice(0, equals);
+      if (FLAGS[command]?.has(name)) {
+        if (equals !== -1) return fail("unexpected_value", `${name} does not take a value.`);
+        if (flags.has(name)) return fail("duplicate_option", `${name} may be given only once.`);
+        flags.add(name);
+        continue;
+      }
       if (OPTIONS[command].has(name)) {
         let value;
         if (equals === -1) {
@@ -116,18 +202,19 @@ export function parseArgs(argv) {
     return { ok: true, command: "help", topic, json };
   }
   if (command === "skill") return parseSkill(action, values, json, fail);
-
-  const rawUrl = values["--url"];
-  const origin = rawUrl === undefined ? DEFAULT_ORIGIN : parseOrigin(rawUrl);
-  if (origin === null) {
-    return fail(
-      "invalid_url",
-      "--url must be a bare https origin such as https://metergraph.example.com, " +
-        "or an http origin on localhost, 127.0.0.1 or [::1]. " +
-        "Credentials, paths, queries and fragments are not accepted.",
-    );
+  if (command === "login") return parseLogin(values, flags, json, fail);
+  if (command === "setup") return parseSetup(values, flags, json, fail);
+  if (command === "verify") return parseVerify(values, flags, json, fail);
+  if (READ_COMMANDS.includes(command)) return parseRead(command, values, json, fail);
+  if (command === "logout") {
+    const paths = parsePaths(values, fail);
+    if (!paths.ok) return paths;
+    return { ok: true, command: "logout", project: paths.project, configDir: paths.configDir, json };
   }
 
+  const origin = parseUrlOption(values);
+  if (origin === null) return fail("invalid_url", INVALID_URL);
+
   const rawTimeout = values["--timeout-ms"];
   const timeoutMs =
     rawTimeout === undefined ? DEFAULT_TIMEOUT_MS : parseTimeout(rawTimeout);
@@ -141,6 +228,39 @@ export function parseArgs(argv) {
   return { ok: true, command: "doctor", origin, timeoutMs, json };
 }
 
+function parseVerify(values, flags, json, fail) {
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const traceId = values["--trace-id"] ?? null;
+  const requestId = values["--request-id"] ?? null;
+  if ((traceId === null) === (requestId === null) ||
+      !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(traceId ?? requestId)) {
+    return fail("invalid_trace_identity", "Provide exactly one --trace-id or --request-id (1 to 200 safe characters).");
+  }
+  const since = values["--since"];
+  const until = values["--until"];
+  const validTime = (value) => typeof value === "string" && value.length <= 40 &&
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value));
+  if (!validTime(since) || !validTime(until) || Date.parse(since) > Date.parse(until) || Date.parse(until) > Date.now()) {
+    return fail("invalid_invocation_window", "--since and --until must bound a past invocation using ISO 8601 timestamps.");
+  }
+  const source = values["--source"] ?? "unspecified";
+  if (!["application", "synthetic", "demo", "import", "unspecified"].includes(source)) {
+    return fail("invalid_source", "--source must be application, synthetic, demo, import or unspecified.");
+  }
+  const days = values["--days"] === undefined ? undefined : parseBounded(values["--days"], 1, 90);
+  if (days === null) return fail("invalid_days", "--days must be a whole number from 1 to 90.");
+  const timeoutMs = values["--timeout-ms"] === undefined ? 30000 : parseTimeout(values["--timeout-ms"], 100, 60000);
+  if (timeoutMs === null) return fail("invalid_timeout", "--timeout-ms must be a whole number from 100 to 60000.");
+  const pollIntervalMs = values["--poll-ms"] === undefined ? 1000 : parseTimeout(values["--poll-ms"], 100, 10000);
+  if (pollIntervalMs === null) return fail("invalid_poll_interval", "--poll-ms must be a whole number from 100 to 10000.");
+  const maxAttempts = values["--max-attempts"] === undefined ? 30 : parseBounded(values["--max-attempts"], 1, 60);
+  if (maxAttempts === null) return fail("invalid_max_attempts", "--max-attempts must be a whole number from 1 to 60.");
+  return { ok: true, command: "verify", project: paths.project, configDir: paths.configDir,
+    traceId, requestId, since, until, source, days, timeoutMs, pollIntervalMs, maxAttempts,
+    open: flags.has("--open"), noBrowser: flags.has("--no-browser"), json };
+}
+
 // Client and runtime are required, so a script states where the skill is
 // used instead of the CLI guessing. Values for clients and runtimes that
 // cannot use project skill files are accepted here and handed off later.
@@ -172,9 +292,195 @@ function parseSkill(action, values, json, fail) {
   return { ok: true, command: "skill", action, client, runtime, project: project ?? null, json };
 }
 
-function parseTimeout(raw) {
+const INVALID_URL =
+  "--url must be a bare https origin such as https://metergraph.example.com, " +
+  "or an http origin on localhost, 127.0.0.1 or [::1]. " +
+  "Credentials, paths, queries and fragments are not accepted.";
+
+function parseUrlOption(values) {
+  const raw = values["--url"];
+  return raw === undefined ? DEFAULT_ORIGIN : parseOrigin(raw);
+}
+
+// The runtime is required so a script states where the browser is. Cloud
+// runtimes are accepted here and handed off later, before any request.
+function parseLogin(values, flags, json, fail) {
+  const runtime = values["--runtime"];
+  if (runtime === undefined) return fail("missing_runtime", "--runtime is required. Use local.");
+  if (!LOGIN_RUNTIMES.includes(runtime) && !HANDOFF_LOGIN_RUNTIMES.includes(runtime)) {
+    return fail("invalid_runtime", "--runtime must be local, cloud or cloud-no-shell.");
+  }
+  const origin = parseUrlOption(values);
+  if (origin === null) return fail("invalid_url", INVALID_URL);
+  const rawWorkspace = values["--workspace"];
+  if (rawWorkspace !== undefined && !UUID.test(rawWorkspace)) {
+    return fail("invalid_workspace", "--workspace must be a workspace ID in UUID form.");
+  }
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const rawTimeout = values["--timeout-ms"];
+  const timeoutMs =
+    rawTimeout === undefined
+      ? LOGIN_DEFAULT_TIMEOUT_MS
+      : parseTimeout(rawTimeout, LOGIN_MIN_TIMEOUT_MS, LOGIN_MAX_TIMEOUT_MS);
+  if (timeoutMs === null) {
+    return fail(
+      "invalid_timeout",
+      `--timeout-ms must be a whole number from ${LOGIN_MIN_TIMEOUT_MS} to ${LOGIN_MAX_TIMEOUT_MS}.`,
+    );
+  }
+  return {
+    ok: true,
+    command: "login",
+    runtime,
+    origin,
+    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    project: paths.project,
+    configDir: paths.configDir,
+    timeoutMs,
+    signup: flags.has("--signup"),
+    noBrowser: flags.has("--no-browser"),
+    reconnect: flags.has("--reconnect"),
+    json,
+  };
+}
+
+function parseSetup(values, flags, json, fail) {
+  const runtime = values["--runtime"];
+  if (runtime === undefined) return fail("missing_runtime", "--runtime is required. Use local.");
+  if (!LOGIN_RUNTIMES.includes(runtime) && !HANDOFF_LOGIN_RUNTIMES.includes(runtime)) {
+    return fail("invalid_runtime", "--runtime must be local, cloud or cloud-no-shell.");
+  }
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const origin = parseUrlOption(values);
+  if (origin === null) return fail("invalid_url", INVALID_URL);
+  const deployment = values["--deployment"] ?? "managed";
+  if (!["managed", "customer-local", "byoc", "oss"].includes(deployment)) {
+    return fail("invalid_deployment", "--deployment must be managed, customer-local, byoc or oss.");
+  }
+  if (deployment === "managed" && (flags.has("--confirm-prerequisites") || values["--agent-token-file"] !== undefined)) {
+    return fail("managed_route_conflict", "Operator prerequisites and agent token files are only for non-hosted deployments.");
+  }
+  if (deployment !== "managed" && values["--url"] === undefined) {
+    return fail("non_hosted_origin_required", "Non-hosted setup requires an explicit --url for the installed service.");
+  }
+  const rawWorkspace = values["--workspace"];
+  if (rawWorkspace !== undefined && !UUID.test(rawWorkspace)) {
+    return fail("invalid_workspace", "--workspace must be a workspace ID in UUID form.");
+  }
+  if (deployment !== "managed" && rawWorkspace === undefined) {
+    return fail("non_hosted_workspace_required", "Non-hosted setup requires an explicit --workspace UUID.");
+  }
+  const agentTokenFile = values["--agent-token-file"] ?? null;
+  if (agentTokenFile !== null && (agentTokenFile === "" || agentTokenFile.includes("\0"))) {
+    return fail("invalid_agent_token_file", "--agent-token-file must name a private absolute file.");
+  }
+  const client = values["--client"] ?? null;
+  if (client === null && !flags.has("--skip-skill")) {
+    return fail("client_required", "Choose --client codex, claude or cursor, or explicitly use --skip-skill.");
+  }
+  if (client !== null && !Object.hasOwn(SKILL_CLIENTS, client)) {
+    return fail("invalid_client", "--client must be codex, claude or cursor.");
+  }
+  if (client !== null && flags.has("--skip-skill")) {
+    return fail("client_conflict", "Use either --client or --skip-skill, not both.");
+  }
+  const envFile = values["--env-file"] ?? ".env";
+  if (envFile === "" || envFile.includes("\0")) return fail("invalid_env_file", "--env-file must name a project-relative env file.");
+  const rawTimeout = values["--timeout-ms"];
+  const timeoutMs = rawTimeout === undefined ? LOGIN_DEFAULT_TIMEOUT_MS :
+    parseTimeout(rawTimeout, LOGIN_MIN_TIMEOUT_MS, LOGIN_MAX_TIMEOUT_MS);
+  if (timeoutMs === null) return fail("invalid_timeout", `--timeout-ms must be a whole number from ${LOGIN_MIN_TIMEOUT_MS} to ${LOGIN_MAX_TIMEOUT_MS}.`);
+  return { ok: true, command: "setup", runtime, origin, originExplicit: values["--url"] !== undefined,
+    deployment, confirmPrerequisites: flags.has("--confirm-prerequisites"), agentTokenFile,
+    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    project: paths.project, configDir: paths.configDir, envFile, client, skipSkill: flags.has("--skip-skill"),
+    timeoutMs, noBrowser: flags.has("--no-browser"), repair: flags.has("--repair"),
+    signup: flags.has("--signup"), reconnect: flags.has("--reconnect"), json };
+}
+
+// Read commands take the project and config directory, one total timeout and,
+// where the endpoint supports them, bounded days, limit and trace filters.
+// Out of range values fail here; nothing is clamped.
+function parseRead(command, values, json, fail) {
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const rawTimeout = values["--timeout-ms"];
+  const timeoutMs =
+    rawTimeout === undefined
+      ? READ_DEFAULT_TIMEOUT_MS
+      : parseTimeout(rawTimeout, READ_MIN_TIMEOUT_MS, READ_MAX_TIMEOUT_MS);
+  if (timeoutMs === null) {
+    return fail(
+      "invalid_timeout",
+      `--timeout-ms must be a whole number from ${READ_MIN_TIMEOUT_MS} to ${READ_MAX_TIMEOUT_MS}.`,
+    );
+  }
+  const takesDays = command === "usage" || command === "traces";
+  const takesLimit = takesDays || command === "routes";
+  let days = null;
+  if (takesDays) {
+    days = values["--days"] === undefined ? READ_DEFAULT_DAYS : parseBounded(values["--days"], 1, READ_MAX_DAYS);
+    if (days === null) return fail("invalid_days", `--days must be a whole number from 1 to ${READ_MAX_DAYS}.`);
+  }
+  let limit = null;
+  if (takesLimit) {
+    const fallback = command === "traces" ? TRACES_DEFAULT_LIMIT : READ_DEFAULT_LIMIT;
+    limit = values["--limit"] === undefined ? fallback : parseBounded(values["--limit"], 1, READ_MAX_LIMIT);
+    if (limit === null) return fail("invalid_limit", `--limit must be a whole number from 1 to ${READ_MAX_LIMIT}.`);
+  }
+  const route = values["--route"] ?? null;
+  if (route !== null && !isSafeFilter(route)) {
+    return fail("invalid_route", "--route must be 1 to 256 characters without control characters.");
+  }
+  const status = values["--status"] ?? null;
+  if (status !== null && status !== "success" && status !== "error") {
+    return fail("invalid_status", "--status must be success or error.");
+  }
+  const cursor = values["--cursor"] ?? null;
+  if (cursor !== null && !isCursor(cursor)) {
+    return fail(
+      "invalid_cursor",
+      "--cursor must be the next_cursor value from an earlier traces result, at most 512 printable characters.",
+    );
+  }
+  return {
+    ok: true,
+    command,
+    project: paths.project,
+    configDir: paths.configDir,
+    timeoutMs,
+    days,
+    limit,
+    route,
+    status,
+    cursor,
+    json,
+  };
+}
+
+function parseBounded(raw, min, max) {
+  if (!/^[0-9]{1,3}$/.test(raw)) return null;
+  const value = Number(raw);
+  return value < min || value > max ? null : value;
+}
+
+function parsePaths(values, fail) {
+  const project = values["--project"];
+  if (project !== undefined && (project === "" || project.includes("\0"))) {
+    return fail("invalid_project", "--project must name an existing directory.");
+  }
+  const configDir = values["--config-dir"];
+  if (configDir !== undefined && (configDir === "" || configDir.includes("\0"))) {
+    return fail("invalid_config_dir", "--config-dir must name a directory path.");
+  }
+  return { ok: true, project: project ?? null, configDir: configDir ?? null };
+}
+
+function parseTimeout(raw, min = MIN_TIMEOUT_MS, max = MAX_TIMEOUT_MS) {
   if (!/^[0-9]{1,6}$/.test(raw)) return null;
   const value = Number(raw);
-  if (value < MIN_TIMEOUT_MS || value > MAX_TIMEOUT_MS) return null;
+  if (value < min || value > max) return null;
   return value;
 }