agent-runtime-cli

name	agent-runtime-cli
description	Queries Watchmen MetricFlow runtime APIs via CLI. Invoke when user wants runtime health checks, metric discovery, dimensions lookup, or metric value/query-file execution.

Agent Runtime CLI

This skill covers the agent-runtime-cli package for querying runtime MetricFlow APIs from a local terminal or automation flow.

When To Invoke

Invoke this skill when the user wants to:

• initialize runtime CLI configuration
• inspect runtime config or discover supported commands
• call runtime health or current date endpoints
• list metrics or inspect metric dimensions
• query metric values with filters, grouping, ordering, or time granularity
• run batch metric queries from a JSON file

Install CLI And Init

Before using this skill:

1. Ensure Python version is 3.12+.
   • If Python is below 3.12, stop and fix the environment first.
2. Ensure CLI is installed:
   • Global: pip install watchmen-agent-runtime-cli
3. Ensure vault config exists (init first if missing):
   • agent-runtime-cli init --vault <vault> --host <host> --pat <token>
4. Prefer module entrypoint for compatibility:
   • poetry run python -m agent_runtime_cli ...

What It Does

• Initializes a local vault and saves runtime connection config
• Uses PAT-based authentication
• Calls runtime endpoints under /metricflow/*
• Returns JSON output suitable for agents, scripts, and pipelines

Vault Layout

Configuration is stored in:

<vault>/.agent-runtime-cli/config.json

Supported Commands

• init
  • Args: --vault, --host, --pat
• config
  • Args: --vault
• discover
  • Args: none
• health
  • Args: --vault
• date
  • Args: --vault
• metrics list
  • Args: --vault
• metrics dimensions
  • Args: metric_name, --vault
• metrics find-dimensions
  • Args: --metrics, --vault
• metrics value
  • Args: metric_name, --group-by, --where, --start-time, --end-time, --order, --limit, --time-granularity, --vault
• metrics query-file
  • Args: file_path, --vault

Common Usage

Initialize:

poetry run agent-runtime-cli init \
  --vault ./runtime-vault \
  --host http://localhost:8000 \
  --pat <PAT>

Check health:

poetry run agent-runtime-cli health --vault ./runtime-vault

List metrics:

poetry run agent-runtime-cli metrics list --vault ./runtime-vault

Query one metric:

poetry run agent-runtime-cli metrics value total_premium \
  --group-by policy_year \
  --time-granularity month \
  --vault ./runtime-vault

Run from JSON file:

poetry run agent-runtime-cli metrics query-file ./queries.json --vault ./runtime-vault

Query File Notes

• The file used by metrics query-file must be a top-level JSON array.
• Each item should be a metric query payload accepted by /metricflow/query_metrics.

Authentication Notes

• Recommended and documented mode is PAT authentication.
• The CLI sends:

Authorization: pat <PAT>

Troubleshooting Checklist

When the user reports a runtime CLI problem, check these items in order:

1. Python version
   • python --version
   • Requires 3.12+
   • If version is lower than 3.12, explain that the runtime CLI requires Python 3.12+ and fix that first.
2. CLI installation
   • Confirm agent-runtime-cli is installed and executable.
   • Prefer poetry run python -m agent_runtime_cli ... when environment resolution is unclear.
3. Vault config
   • Confirm <vault>/.agent-runtime-cli/config.json exists.
   • If missing, run init.
4. Host and PAT
   • Verify host is reachable.
   • Verify PAT is present and valid.
5. Runtime endpoint
   • Check /metricflow/health first before deeper troubleshooting.
6. Query payload
   • Confirm metric names, dimensions, time range, filters, and JSON file format are valid.

Known Issues List

Maintain this section as a living issue list for recurring runtime CLI problems.

• Python version mismatch
  • Symptom: CLI fails to install or run.
  • Cause: Python version is below 3.12.
  • Fix: switch to Python 3.12+.
• Missing vault config
  • Symptom: command cannot find config or PAT.
  • Cause: vault was not initialized.
  • Fix: run agent-runtime-cli init --vault <vault> --host <host> --pat <token>.
• Invalid or missing PAT
  • Symptom: runtime returns 401 or 403.
  • Cause: PAT missing, expired, or incorrect.
  • Fix: re-run init with a valid PAT or update the vault config.
• Runtime health check failed
  • Symptom: /metricflow/health is unreachable or returns 4xx/5xx.
  • Cause: host is wrong, service is down, or networking is blocked.
  • Fix: verify host, service status, and network access.
• Query file parse failure
  • Symptom: metrics query-file fails before execution.
  • Cause: file is not valid JSON or top level is not an array.
  • Fix: correct the JSON structure.

Issue List Maintenance

Each time you solve a new runtime CLI problem, update the Known Issues List in this skill.

• Add a new item when the problem pattern is new and likely to recur.
• Update an existing item when the root cause or fix becomes clearer.
• Keep each item short and structured as: Symptom, Cause, Fix.
• Prefer practical, reproducible issues over one-off local accidents.
• If the issue is only temporary and not reusable, do not add it.

References

• Command catalog: references/command-catalog.md
• Runtime payload and endpoint summary: references/source-of-truth.md
• Installer script: ../../scripts/install-skill.sh

Error Guidance

• If vault config is missing, run init first.
• If Python version is below 3.12, upgrade Python before continuing.
• If PAT is missing, provide --pat during init or configure it in the vault.
• If query file parsing fails, verify the file is valid JSON and the top level is an array.
• If runtime returns 4xx/5xx, verify host, PAT, and endpoint availability.