metergraph-cli 0.2.0 → 0.2.2

package/README.md

@@ -13,7 +13,7 @@ token and route metadata back. Every command has stable `--json` output and exit
 so agents can run it as well as people.
 
 ```sh
-npx --yes metergraph-cli --help
+npx --yes metergraph-cli@latest --help
 ```
 
 Published on npm as `latest`. See the [changelog](https://github.com/metergraph/cli/blob/main/CHANGELOG.md).
@@ -21,12 +21,13 @@ Published on npm as `latest`. See the [changelog](https://github.com/metergraph/
 ## Quickstart
 
 **1. Set up the project.** Run this in your project directory. It opens your browser to
-sign in and choose a workspace, asks a workspace member to approve an ingest-only key,
+sign in and choose a workspace, asks a workspace member to approve an ingest-only key
+(on the same page as sign in, where the service supports it),
 writes `METERGRAPH_APP_TOKEN` and `METERGRAPH_INGEST_URL` to a private `.env`, and
 installs the skill for your coding agent.
 
 ```sh
-npx --yes metergraph-cli setup --runtime local --client claude
+npx --yes metergraph-cli@latest setup --runtime local --client claude
 ```
 
 Use `--client codex` or `--client cursor` for the other agents.
@@ -39,19 +40,20 @@ ID or request ID and when the call started and ended.
 exact trace is visible in your workspace.
 
 ```sh
-npx --yes metergraph-cli verify --trace-id TRACE_ID \
+npx --yes metergraph-cli@latest verify --trace-id TRACE_ID \
   --since 2026-01-08T12:00:00Z --until 2026-01-08T12:00:05Z
 ```
 
 Then read what Metergraph has recorded:
 
 ```sh
-npx --yes metergraph-cli usage --days 7      # calls, errors, cost and tokens per route per day
-npx --yes metergraph-cli traces --limit 20   # one page of trace metadata
+npx --yes metergraph-cli@latest usage --days 7      # calls, errors, cost and tokens per route per day
+npx --yes metergraph-cli@latest usage --group-by route --today   # most expensive route today (UTC)
+npx --yes metergraph-cli@latest traces --limit 20   # one page of trace metadata
 ```
 
-To install it globally instead, run `npm install -g metergraph-cli`. The command is
-`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.0`, when a
+To install it globally instead, run `npm install -g metergraph-cli@latest`. The command is
+`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.2`, when a
 script must not change with the `latest` tag. Previews use the `next` tag.
 
 ## Requirements
@@ -67,8 +69,11 @@ Sign in needs a service that offers Metadata-only CLI grants and grant revocatio
 service without them is reported as unsupported, and the CLI never falls back to
 broader access. `setup` also needs the deployment's ingest bootstrap API and approval by
 a workspace member. Sign in needs a browser on the same machine. From SSH sessions,
-cloud development environments and CI, `login` and `setup` hand off to a local machine
-instead (exit 6).
+cloud development environments and CI, `login` and `setup` exit 6 with a structured
+`next_action`: a person creates a coding-agent key with Metadata access on the Keys
+page and saves it as the secret `METERGRAPH_AGENT_TOKEN`, and the read commands use it
+after verifying the origin, workspace, scope and capabilities. Ingest setup still runs
+on a local machine.
 
 ## Using it with a coding agent
 
@@ -79,7 +84,7 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
   network access:
 
   ```sh
-  npx --yes metergraph-cli skill install --client codex
+  npx --yes metergraph-cli@latest skill install --client codex
   ```
 
   Python users can run `pip install metergraph-skills` and
@@ -93,7 +98,7 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
   the `metergraph/skills` plugin marketplace instead.
 
   ```sh
-  npx --yes metergraph-cli skills install --client claude
+  npx --yes metergraph-cli@latest skills install --client claude
   ```
 
   `--runtime` defaults to `local`. Pass `--runtime cloud` when the client runs in a
@@ -120,7 +125,7 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
 Suggested `AGENTS.md` or `CLAUDE.md` lines for a project that uses Metergraph:
 
 ```md
-- Metergraph CLI: `npx --yes metergraph-cli <command> --json`. Check exit codes;
+- Metergraph CLI: `npx --yes metergraph-cli@latest <command> --json`. Check exit codes;
   follow `data.next_action` on failure.
 - After changing instrumented code, run the app once and confirm the trace with
   `metergraph verify` before reporting that tracing works.
@@ -132,8 +137,8 @@ Suggested `AGENTS.md` or `CLAUDE.md` lines for a project that uses Metergraph:
 | --- | --- | --- |
 | `setup` | Sign in, choose a workspace, write the ingest key to `.env`, record the repository, install the skill | Yes |
 | `verify` | Confirm that one exact trace, by trace ID or request ID, reached the workspace | Yes |
-| `usage` | Daily calls, errors, cost, tokens and latency per route | Yes |
-| `traces` | One page of trace metadata, with a cursor for the next page | Yes |
+| `usage` | Daily calls, errors, cost, tokens and latency per route, or cost grouped by provider, model, route or UTC day with exact filters, rankings and a prior-period comparison; filtered by exact metadata or grouped by one metadata key | Yes |
+| `traces` | One page of trace metadata, filtered by route, status or exact metadata, with a cursor for the next page | Yes |
 | `routes` | Routes with call counts and evaluation contract status | Yes |
 | `status` | Whether the project is signed in, and to which workspace | Yes |
 | `context` | Workspace details and retention | Yes |
@@ -170,7 +175,7 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not
 | 13 | `revocation_unconfirmed` | Local credentials were removed, but the service did not confirm that the grant was revoked. |
 | 14 | `capability_unavailable` | The service does not make this read available to the project's Metadata grant. No data was read. |
 | 15 | `permission_denied` | The service refused this read for the signed in grant, for example for a missing scope or permission. |
-| 16 | `rate_limited` | The service asked the CLI to slow down. Nothing was retried. Try again later. |
+| 16 | `rate_limited` | The service asked the CLI to slow down. Try again later. Only setup retries, after a short Retry-After, to keep its approval. |
 | 17 | `cancelled` | A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry. |
 | 18 | `action_required` | A person must act before the command can finish; `data.next_action` says what to do. `login` and `setup` with `--json --no-browser` exit with this as soon as an approval URL exists (`next_action.kind: "open_url"`), while a background process waits for the approval until `--timeout-ms`. After approval, run the same command again to continue. |
 

package/assets/skill/SKILL.md

@@ -57,6 +57,53 @@ pass the same `--workspace` UUID each time, and give each repository its own
 identity. The SDK warning that repository identity is not configured does not
 stop capture.
 
+## Pick the CLI path for where the agent runs
+
+Check `metergraph --help` first. If the read commands' help lists
+`--agent-token-file`, the CLI also accepts a coding-agent key with Metadata
+access from the `METERGRAPH_AGENT_TOKEN` environment variable. Use one sequence:
+
+| Where the agent runs | Sequence |
+|---|---|
+| Local shell, hosted, new workspace | `metergraph setup --runtime local --client <client> --json --no-browser`, rerun after each approval, then `metergraph status --json`. Add `--signup` for a person with no hosted account. |
+| Local shell, hosted, existing workspace | `metergraph login --runtime local --workspace <uuid> --json --no-browser`, then `metergraph status --json`. |
+| Local shell, customer-local or customer-owned AWS | `metergraph setup --runtime local --client <client> --deployment customer-local` (or `byoc`) `--url <origin> --workspace <uuid> --json --no-browser`. Follow its `next_action` for each prerequisite, and add `--confirm-prerequisites` only after the person confirms them. Then `metergraph status --json`. Without `--deployment`, setup and login go to the hosted service. |
+| Local container (Docker, local dev container) | As a local shell. If the browser cannot reach the container's sign in callback, use the key sequence below. |
+| SSH, Codespaces, Gitpod, Cloud Shell, remote dev container, CI: hosted, customer-local or customer-owned AWS | The person signs in (or signs up, on the hosted service only) on their own device, opens the Keys page of the deployment and workspace the agent should read, creates a coding-agent key with Metadata access, and saves it in this environment's secret settings, or as a CI secret, named `METERGRAPH_AGENT_TOKEN`. Then run `metergraph status --json` and `metergraph usage --json`. Add `--workspace <uuid>` to make a key for another workspace fail. For a non-hosted deployment, pass `--url <origin>` (or set `METERGRAPH_URL`) with its address. |
+| Any runtime: open-source self-hosted server | The CLI read commands do not support the open-source server; use its MCP route (below). There are no accounts and no Keys page: the operator gives the person one of the server's `MG_AGENT_TOKENS` values for the client's private MCP settings. |
+| Has a Metadata key but no saved sign in | The same key sequence. If the project has a `.metergraph/project.json`, it pins the origin and workspace the key must match. |
+
+`.metergraph/project.json` names the deployment origin and workspace ID. In a
+public repository, keep it untracked (for example in `.gitignore`) and do not
+commit it: that would publish the workspace ID. In CI for a public repository,
+the read commands' JSON includes workspace IDs and per-route usage: write it to a file or
+a masked step instead of the public job log, and print only what the person
+needs.
+
+Before answering a cost question from the CLI, confirm the workspace and what
+it offers: `metergraph status --json` (the verified workspace must be the one
+the person means) and `metergraph capabilities --json`. Then run the smallest
+bounded `usage` read that answers it. Grouped usage needs a CLI that has it:
+run `metergraph help usage` first, and use `--group-by` only when that help
+lists it (for example `metergraph usage --group-by route --today --json` for
+the most expensive route today). An older CLI has only
+`metergraph usage --days N --json` (cost per route and day); say that grouping
+by provider, model or metadata needs a newer CLI or the
+`metergraph_get_usage_aggregates` tool, and do not invent flags. Grouped
+usage windows are UTC days; plain `usage --days N` is the last N x 24 hours,
+rolling. `metergraph-investigate` covers the rest. A deployment without grouped
+usage exits 14 with a `next_action` that names the read it supports.
+
+When `login`, `setup` or a read cannot finish where it runs, it prints
+`data.next_action`. Follow it: `use_agent_key` lists the person's steps and the
+commands to run afterwards; `replace_agent_key`, `use_metadata_only_key` and
+`use_workspace_key` mean the key was refused, was broader than Metadata, or
+belongs to another workspace. Never ask the person to paste the key into chat or
+a command, and never put it in a project file. Ingest setup cannot run over SSH,
+in a cloud workspace or in CI; it runs on the person's machine. The Metadata key
+is separate from the application's ingest key and never replaces it. Debug and
+Replay keys are refused by the CLI, not reduced.
+
 ## Route honestly
 
 | Client and runtime | Hosted | Customer-local bundle | Customer AWS | Open source self-hosted |
@@ -103,10 +150,12 @@ rather than improvising the analysis steps.
 
 ## 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.
+Read through the `metergraph` CLI first when it is installed and can read the workspace: it returns the same Metadata evidence as the MCP tools in far fewer tokens. Use the MCP tools for what the CLI does not cover (incidents, ingestion health, reports, retained content and replay) and in clients with no shell. Being connected means either one; stop for setup only when neither can read the workspace.
+
+1. Confirm the workspace and what it offers. With the CLI: `metergraph status --json` (continue when `data.authenticated` is true and `data.workspace.match` is true. When `match` is null because no workspace was pinned, name `data.workspace.actual` and continue only after the person confirms it is the one they mean. Otherwise follow `data.next_action`) and `metergraph capabilities --json`. With MCP: `metergraph_get_workspace_context`, then `metergraph_get_capabilities`. Verify the intended workspace, deployment profile, available reads, required scopes and privacy classes. A wrong workspace or failed authorization on one path is a reason to use the other path when it can read the intended workspace; stop when neither can, or when the capability the question needs is unavailable.
+2. Confirm the question, route and explicit UTC time window. Choose the smallest available read, and always pass `--json` to the CLI: grouped usage (`metergraph usage --group-by ... --json`, or `metergraph_get_usage_aggregates`) or `metergraph usage --days N --json` / route metadata for aggregate questions, `metergraph traces --days N --limit 1 --json` with `--route` when known and `--status error` only for a failed trace (or `metergraph_query_traces` with a small limit, which also takes an exact trace or request ID) for a failed or anomalous trace, and the incidents tool for known anomalies. Check that `metergraph help <command>` lists an option before using it, and use the matching MCP tool when it does not. 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.
+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. Never conclude that a commit, deploy or config change did or did not change cost from source code or a git diff alone; a diff is a hypothesis until bounded usage reads for the same route before and after the change reached production agree, with completeness and warnings cited.
 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/. If `metergraph setup` already ran in this project, it delivered the ingest credential: the project's `.env` holds `METERGRAPH_APP_TOKEN` and `METERGRAPH_INGEST_URL`. Use them; do not ask for or create another key, and never print their values. The SDK reads the process environment, not `.env`, so load it when you run the application (for example `set -a; . ./.env; set +a`, python-dotenv or `node --env-file=.env`). Otherwise confirm the ingestion destination and obtain a separate ingest credential securely. Ask before running anything that calls a paid model provider, and do not initiate provider calls or paid work merely to validate setup. Confirm the exact trace with `metergraph verify`; if the CLI is not installed, or `metergraph --version` lacks `verify`, use `npx --yes metergraph-cli@next verify`. 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.
+For an empty workspace, use https://www.metergraph.dev/docs/agents/instrument-a-repo/. If `metergraph setup` already ran in this project, it delivered the ingest credential: the project's `.env` holds `METERGRAPH_APP_TOKEN` and `METERGRAPH_INGEST_URL`. Use them; do not ask for or create another key, and never print their values. The SDK reads the process environment, not `.env`, so load it when you run the application (for example `set -a; . ./.env; set +a`, python-dotenv or `node --env-file=.env`). Otherwise confirm the ingestion destination and obtain a separate ingest credential securely. Ask before running anything that calls a paid model provider, and do not initiate provider calls or paid work merely to validate setup. Confirm the exact trace with `metergraph verify`; if the CLI is not installed, or `metergraph --version` lacks `verify`, use `npx --yes metergraph-cli@latest verify`. 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

@@ -3,7 +3,7 @@
   "name": "metergraph",
   "file": "SKILL.md",
   "source_url": "https://www.metergraph.dev/SKILL.md",
-  "sha256": "e7fc4eb7a22eeb16c357bede9d0a080ad3b415aaab1d9c72f164d5350d48c4b1",
-  "size": 13664,
-  "revision": "sha256-e7fc4eb7a22e"
+  "sha256": "ebf784673eff0280d85974504f93c683a1dabfb54156c9d27e091131462e9d5f",
+  "size": 19764,
+  "revision": "sha256-ebf784673eff"
 }

package/assets/skills/manifest.json

@@ -1,13 +1,13 @@
 {
   "manifest_version": 1,
   "repository": "metergraph/skills",
-  "commit": "dda4d5f130448f12a7fb2549ed264503d8b51d8d",
+  "commit": "39411ce1eceed6929ab3e5c4c20649f02e8eabb4",
   "skills": [
     {
       "name": "metergraph-analyze",
-      "sha256": "e8bf1debf62aa7d33d3dd363e5d95d8f781e8ca23cde4619b5bb4133dd47a7a5",
-      "size": 9360,
-      "revision": "sha256-e8bf1debf62a"
+      "sha256": "c45756ad1d33a360c7c845ca299d8c1ab1e2b8162865f635bc25c78358c2a1e6",
+      "size": 12148,
+      "revision": "sha256-c45756ad1d33"
     },
     {
       "name": "metergraph-candidates",
@@ -23,9 +23,9 @@
     },
     {
       "name": "metergraph-investigate",
-      "sha256": "775dbe7ca1100b17638d0905302ef1324694a60b90372c6c3df7b598a8f70438",
-      "size": 6091,
-      "revision": "sha256-775dbe7ca110"
+      "sha256": "470579faf9e8b5f1a562060d51ec5a71d1b9c47213403a2447dd40af56a74869",
+      "size": 19331,
+      "revision": "sha256-470579faf9e8"
     },
     {
       "name": "metergraph-iterate",
@@ -35,9 +35,9 @@
     },
     {
       "name": "metergraph-local-bundle",
-      "sha256": "692cd8952a8a8896ec2c06091b329a7a01912e261e87d62a9458452172a7c9b0",
-      "size": 12245,
-      "revision": "sha256-692cd8952a8a"
+      "sha256": "c31286b7ee6dd8fc228e81565662ebaf4b0faf2ae92229602baf7c809202491b",
+      "size": 12265,
+      "revision": "sha256-c31286b7ee6d"
     },
     {
       "name": "metergraph-model-swap",
@@ -47,15 +47,15 @@
     },
     {
       "name": "metergraph-onboarding",
-      "sha256": "6e6f418933f37b34437035ab3171344d43f37dee3770815b19f97efb62e5f1d1",
-      "size": 10267,
-      "revision": "sha256-6e6f418933f3"
+      "sha256": "409d105f3b042514fd347a1fffc5489a94c01d1bc8aac55800e8c9f13a66a2c1",
+      "size": 10751,
+      "revision": "sha256-409d105f3b04"
     },
     {
       "name": "metergraph-report",
-      "sha256": "58add8f6a32191e6fc01ca533a700e190a8e6da412e619bca38c65a481ea9fb5",
-      "size": 4521,
-      "revision": "sha256-58add8f6a321"
+      "sha256": "0cdbeb684c4f7f87932784db832f376cff984fe0220a1167f1a73edd550450b7",
+      "size": 5471,
+      "revision": "sha256-0cdbeb684c4f"
     },
     {
       "name": "metergraph-workloads",

package/assets/skills/metergraph-analyze/SKILL.md

@@ -116,14 +116,72 @@ restate what you are starting and proceed. Otherwise ask and wait.
    the returned run instead of starting another. On `precondition_failed`,
    report the `reason` and stop.
 4. Poll `metergraph_get_analysis_run` with the `run_id` at a modest interval
-   (about every 30 to 60 seconds) and tell the user the status as it changes.
-   Do not restart a run because it is slow. Stop polling when the status is
-   final, and say if it failed, with its `error_code`.
+   (about every 30 to 60 seconds). Do not restart a run because it is slow.
+   Stop polling when the status is final, and say if it failed, with its
+   `error_code`.
+5. After the start and after every poll, write a progress report in the
+   shape shown under "Show run progress" before you wait, set a timer or
+   schedule the next check. The start response already carries
+   `run.stages`, so the reply that starts the run has one too. A one-line
+   status such as "The run is exporting; I'll check again in a minute" is
+   not a progress report. The graphic is required every time.
+
+## Show run progress
+
+Draw the stages from `run.stages.items`, in the order returned. Use each
+item's `state` exactly as given. Never decide a stage's state from `status`,
+trace names or the report.
+
+Render one line with a marker per state: `✓` completed, `●` current, `✗`
+failed, `–` skipped, `○` not started. For example:
+
+```
+✓ queued → ✓ exporting → ✓ analyzing → ● classified → ○ importing → ○ completed
+```
+
+If the client can draw a richer inline graphic, you may use one. Keep the
+same order and states, and make the states distinct without relying on
+colour alone.
+
+Under the graphic, always write a plain-text line that says the same thing:
+the stages that are done, the current stage, and the stages still to come.
+
+Every check-in, including the reply that starts the run, has this shape:
+
+````
+Run 3f2a… at 19:34 UTC:
+
+```
+✓ queued → ✓ exporting → ✓ analyzing → ● classified → ○ importing → ○ completed
+```
+Done: queued, exporting, analyzing. Now: classified, since 19:23 UTC
+(11 minutes, unchanged since the last check). Still to come: importing,
+completed. No error, no report yet. Next check in about a minute.
+````
+
+- **Time in the current stage.** Take it from the current item's
+  `entered_at` and the response's `provenance.generated_at`, which is the
+  check time. Say when you last checked, and say plainly when the stage has
+  not changed since the last check. Never give a percentage, an ETA or a
+  time remaining. The run data supports neither.
+- **Finished.** On `completed`, draw the items as returned, like any other
+  check: the stages the run passed through are `✓`, and a stage it never
+  entered stays `–` skipped. When `report.available` is true, read the
+  report (step 6) and give any link it returns exactly as given. When it is
+  false, say plainly that no report exists yet.
+- **Failed.** On `failed`, mark the stage it stopped in with `✗`, give the
+  `error_code`, and leave the later stages `○`.
+- **No stage data.** When `run.stages.available` is false, or `stages` is
+  missing, show no graphic. Say the stage breakdown is unavailable for this
+  run (`unavailable_reason`, when present). Report the `status`, the
+  timestamps, the `error_code` if the run failed, and whether a report
+  exists. Never mark stages complete by inference.
 
 ## 6. Read the report and recommend
 
 When `report.available` is true, call `metergraph_get_report` with
-`report.analysis_id`. Use the summary format and report link in
+`report.analysis_id`. While it is false, do not look for a report under
+another or guessed ID. Use the summary format and report link in
 `metergraph-report` when it is installed. Present:
 
 - the report `outcome`: `opportunities`, `no_opportunities`,