metergraph-cli 0.0.0-stage → 0.2.0-preview.0

package/assets/skill/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: metergraph
+description: Route Metergraph setup by client, execution runtime and deployment, then perform bounded evidence-backed investigation when already authenticated.
+---
+
+# Use Metergraph with your agent
+
+Public setup: https://www.metergraph.dev/docs/guides/agent-access/
+Connection and troubleshooting: https://www.metergraph.dev/docs/guides/agent-access/
+
+## Confirm setup before producing instructions
+
+Ask for or confirm these non-secret choices. Do not guess from the agent brand:
+
+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.
+
+For the commercial customer-local bundle, direct them to https://www.metergraph.dev/docs/self-host/local/#the-customer-local-bundle and the signed public release. They need a separate pull-only registry credential from Metergraph to pull the images; the public bundle download does not grant registry access. Verify the release before installation. Local admin credentials from the bundle's private configuration provide dashboard sign-in; create a coding-agent key in that installation's Keys page. Do not substitute hosted signup or a hosted key. Do not clone the private implementation or run development seed commands.
+
+For customer-owned AWS, direct them to https://www.metergraph.dev/docs/self-host/aws/. An operator provisions the installation, identity and membership. There is no public signup. Ask for the installation's actual reachable address and use a coding-agent key from its Keys page. Its default internal load balancer is private, and its Agent Access surface excludes trace content and replay.
+
+For the open-source self-hosted server, direct them to https://www.metergraph.dev/docs/self-host/local/#the-open-source-server. No Metergraph account, commercial release, registry credential or Keys page is needed. The operator configures static `MG_AGENT_TOKENS` separately from ingestion `MG_TOKENS`. Agent Access is content-blind and does not provide replay, incidents, ingestion health or pipeline reports. Use the actual local server address; do not ask them to mint a hosted coding-agent key.
+
+## Keep credentials outside chat
+
+Direct the human to the correct workspace's Keys page and private client configuration. Leave replay disabled unless separately authorized. Never ask for, quote, log or include raw keys in a prompt. Registry pull, ingestion, Agent Access and model/provider credentials are different credentials. Use the client's supported secure environment/settings input. Keep token-bearing configuration out of shell history and committed project files. Rotation/revocation happens in Keys; a revoked token must be rejected on the next request.
+
+## Answer capability and documentation questions
+
+Use https://www.metergraph.dev/docs/ for public product documentation and https://www.metergraph.dev/docs/guides/mcp-server/ for Agent Access tool details. Explain what the docs say about an edition, then use `metergraph_get_capabilities` to confirm what the connected workspace actually supports. Cite the public page you used and distinguish a missing capability from an empty workspace. Do not read retained content or run replay just to answer a documentation question.
+
+## When already connected: bounded investigation
+
+1. Call `metergraph_get_workspace_context` and `metergraph_get_capabilities` first. Verify the intended workspace, deployment profile, available tools, required scopes and privacy classes. Stop on wrong workspace, unavailable capabilities or failed authorization.
+2. Confirm the question, route and explicit time window. Choose the smallest available tool: bounded usage/route metadata for aggregate questions, incidents for known anomalies, or `metergraph_query_traces` with a small limit (start with 1) for a failed/anomalous trace. Follow cursors only within the agreed bound. Never request generic SQL or unbounded data.
+3. Start with metadata. Retained-content debugging and report evidence are separate content-bearing tools; confirm the user's content intent and capability before calling them. Replay is a separate scope and can send data to a provider and spend money. Obtain explicit bounded execution/data-egress authority before any replay. Read access grants no eval-write, analysis-run or production-mutation authority.
+4. Explain the failure or anomaly using only returned evidence. Cite workspace, time window, provenance, trace/report IDs, completeness/coverage, warnings and working app links when returned. Do not fabricate links. Distinguish no data, incomplete evidence, unavailable capability, classification pending, stale/mismatched identity, failed analysis and missing report. An empty result alone does not prove absence of traffic.
+5. An optional approved replay must be eligible, bounded and non-persistent. Do not claim that it changed production telemetry or fixed the application. Refuse autonomous dashboard mutations or production configuration changes.
+
+For an empty workspace, use https://www.metergraph.dev/docs/agents/instrument-a-repo/ after confirming the ingestion destination and obtaining a separate ingest credential securely. Do not initiate provider calls or paid work merely to validate setup. Ingestion accepted, processed, retained content, classification readiness and analysis readiness are distinct states. Label synthetic/demo fixtures; they do not prove a first real application trace.

package/assets/skill/manifest.json

@@ -0,0 +1,9 @@
+{
+  "manifest_version": 1,
+  "name": "metergraph",
+  "file": "SKILL.md",
+  "source_url": "https://www.metergraph.dev/SKILL.md",
+  "sha256": "57b920677adf62759c7221629327192a2d16b7e6034f7948ffd96cee402d4891",
+  "size": 10426,
+  "revision": "sha256-57b920677adf"
+}

package/bin/metergraph.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+// A closed pipe on stdout (for example "metergraph --help | head -1") is not
+// a CLI failure.
+process.stdout.on("error", () => {});
+
+process.exitCode = await main(process.argv.slice(2), {
+  stdout: process.stdout,
+  stderr: process.stderr,
+});

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "metergraph-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0-preview.0",
+  "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"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/metergraph.js",
+    "src/*.js",
+    "assets/skill/SKILL.md",
+    "assets/skill/manifest.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:package": "node --test test/package/*.test.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "author": "Metergraph",
+  "homepage": "https://www.metergraph.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metergraph/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/metergraph/cli/issues"
+  },
+  "keywords": [
+    "metergraph",
+    "cli",
+    "llm",
+    "cost-tracking"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/args.js

@@ -0,0 +1,486 @@
+import {
+  DEFAULT_ORIGIN,
+  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";
+
+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: 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) {
+  const json = argv.includes("--json");
+
+  if (argv.includes("--help") || argv.includes("-h")) {
+    const topic = argv.find((arg) => HELP_TOPICS.has(arg)) ?? null;
+    return { ok: true, command: "help", topic, json };
+  }
+
+  let command = null;
+  let action = null;
+  let topic = null;
+  let version = false;
+  const values = {};
+  const flags = new Set();
+
+  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) {
+    const arg = argv[index];
+    const position = index + 1;
+
+    if (arg === "--json") continue;
+
+    if (command === null && !version && COMMANDS.has(arg)) {
+      command = arg;
+      continue;
+    }
+    if (command === null && arg === "--version") {
+      version = true;
+      continue;
+    }
+    if (command === "help" && topic === null && HELP_TOPICS.has(arg)) {
+      topic = arg;
+      continue;
+    }
+    if (command === "skill" && action === null && SKILL_ACTIONS.has(arg)) {
+      action = arg;
+      continue;
+    }
+
+    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) {
+          index += 1;
+          value = argv[index];
+        } else {
+          value = arg.slice(equals + 1);
+        }
+        if (value === undefined) {
+          return fail("missing_value", `${name} requires a value.`);
+        }
+        if (values[name] !== undefined) {
+          return fail("duplicate_option", `${name} may be given only once.`);
+        }
+        values[name] = value;
+        continue;
+      }
+    }
+
+    if (command === null && !version && !arg.startsWith("-")) {
+      return fail(
+        "unknown_command",
+        `Unknown command at argument ${position}. Run "metergraph --help" for usage.`,
+      );
+    }
+    if (command === "skill" && action === null && !arg.startsWith("-")) {
+      return fail(
+        "unknown_subcommand",
+        `Unknown skill subcommand at argument ${position}. Use install or update.`,
+      );
+    }
+    return fail(
+      "unknown_argument",
+      `Unrecognized argument at position ${position}. Run "metergraph --help" for usage.`,
+    );
+  }
+
+  if (version) return { ok: true, command: "version", json };
+  if (command === null || command === "help") {
+    return { ok: true, command: "help", topic, json };
+  }
+  if (command === "skill") return parseSkill(action, values, json, fail);
+  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);
+  if (timeoutMs === null) {
+    return fail(
+      "invalid_timeout",
+      `--timeout-ms must be a whole number from ${MIN_TIMEOUT_MS} to ${MAX_TIMEOUT_MS}.`,
+    );
+  }
+
+  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.
+function parseSkill(action, values, json, fail) {
+  if (action === null) {
+    return fail(
+      "missing_subcommand",
+      'skill requires a subcommand: install or update. Run "metergraph help skill" for usage.',
+    );
+  }
+  const client = values["--client"];
+  if (client === undefined) {
+    return fail("missing_client", "--client is required. Use codex, claude or cursor.");
+  }
+  if (!Object.hasOwn(SKILL_CLIENTS, client) && !Object.hasOwn(HANDOFF_SKILL_CLIENTS, client)) {
+    return fail("invalid_client", "--client must be codex, claude or cursor.");
+  }
+  const runtime = values["--runtime"];
+  if (runtime === undefined) {
+    return fail("missing_runtime", "--runtime is required. Use local or cloud.");
+  }
+  if (!SKILL_RUNTIMES.includes(runtime) && !HANDOFF_SKILL_RUNTIMES.includes(runtime)) {
+    return fail("invalid_runtime", "--runtime must be local or cloud.");
+  }
+  const project = values["--project"];
+  if (project !== undefined && (project === "" || project.includes("\0"))) {
+    return fail("invalid_project", "--project must name an existing directory.");
+  }
+  return { ok: true, command: "skill", action, client, runtime, project: project ?? null, json };
+}
+
+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 || value > max) return null;
+  return value;
+}