feat: add poly metrics commands (list, export, add, edit, import)

[bill-parker]

Summary

Add poly metrics CLI commands for managing custom metrics in Agent Studio projects:

• list
• export / import (YAML)
• add
• edit

Motivation

Custom metrics are currently only manageable through the Agent Studio UI. This adds full CLI support so teams can script metric setup, export/import metric definitions across projects, and integrate metric management into CI pipelines.

Changes

Commands

• poly metrics list — display all custom metrics in a Rich table (Name, Type, Active, API, Description) with active/inactive count summary; --json for machine-readable output
• poly metrics export [file] — export all metrics as YAML to stdout or a file; --json outputs JSON instead
• poly metrics add — create a new metric with --name, --type, --description, --api, --expected-values; omit required flags for interactive mode (name text input, type selector, description prompt, API confirm via questionary)
• poly metrics edit <name> — update an existing metric's --description, --api (bool), --active (bool), or --expected-values; --api/--active accept true/false or can be used bare to set true. When called with just a metric name and no flags, enters interactive mode: fetches the metric, displays current values, and prompts with questionary.checkbox() to select which fields to update. --expected-values is only offered for string-type metrics. Friendly error when metric not found (404).
• poly metrics import <file> — bulk-import metrics from a YAML file; creates new metrics and skips existing ones; --dry-run previews what would be created/skipped and warns about remote-only metrics that won't be deleted

API flag workaround

The server's create_custom_metric route hardcodes api=False, ignoring the client-supplied value (the AS UI also doesn't set this on create). When --api is passed, under the hood the the CLI follows up with a PATCH to set api=True.

Implementation notes

• Platform API: 5 new methods on PlatformAPIHandler; make_request extended with files (multipart upload) and response_format (YAML parsing) params . These were needed for import and export YAML as file handling only previously supported JSON.
• Tests: 30 unit tests across 8 test classes

import/export flow was chosen here as the implementation details of metrics require that metrics
have project scope (not branch scope) and cannot be deleted once written.

In this case, using a local file to manage additions and changes could give way to merge issues
and user confusion where deleted items are not actually removed.
For this reason I have opted to model this feature on the platform features,
with one exception that API can be set on metric creation.

Test strategy

• Added/updated unit tests
• Manual CLI testing (poly metrics for all subcommands)
• Tested against a live Agent Studio project

Manual test spreadsheet: Google Sheet

Checklist

• ruff check . and ruff format --check . pass
• pytest passes
• No breaking changes to the poly CLI interface (or migration path documented)
• Commit messages follow conventional commits

Screenshots / Logs

poly metrics list

poly metrics add (interactive)

poly metrics add — API flag prompt

poly metrics add --expected-values (JSON output)

poly metrics add --api (JSON output)

[github-actions]

Coverage Report

Base (main)	PR	Change
73.0%	73.4%	+0.4% ✅

Changed file coverage

File	Coverage	Change
poly/output/console.py	27.0%	+1.9% ✅
poly/handlers/interface.py	67.0%	+4.0% ✅
poly/handlers/platform_api.py	73.1%	+2.6% ✅
poly/cli.py	78.8%	+0.3% ✅

[Ruari-Phipps]

My main comment is on general structure.
I feel like we should be running this through the project.py
So cli -> project -> interface -> api
Adds a little more but thats the general pattern I've been aiming for so far. I might adjust this going forward.

Also, would be good to have some of the logic in here being moved into the project.py. This file is basically just a forwarder to the correct endpoint and some error handling. Stuff like validating and reading the files should be in there

[Ruari-Phipps]

Should this be in cli_test?

[northdpole]

👋 The failing trufflehog check on this PR is a false positive — there is no credential here, and nothing needs rotating.

The scanner flagged a test function name, src/poly/tests/metrics_test.py:321:

def test_add_duplicate_metric_friendly_error(self, mock_load, mock_create, mock_error):

TruffleHog's Lob detector matches \b((live|test)_[a-zA-Z0-9_]{35})\b with no keyword-proximity requirement, and its keyword prefilter is literally {"live_", "test_"} — the pytest naming convention. So any test_* identifier that is exactly 40 characters long matches. This one is. It gets reported as verified because the detector counts HTTP 403/422 from api.lob.com as success, so a function name passes verification.

Nothing to change on your side — the name is fine, please don't rename it.

#263 fixes this at the source (excludes the Lob detector, which we don't use, and makes the scanner actually print the file, line and match instead of a bare Found verified Lob result). Once that merges, rebase on main and this check will go green.

Sorry for the noise — the output gave you no way to tell a real leak from this.

[linear-code]

DEVP-180