@metrio-ai/cli 1.0.1 → 1.2.0

package/dist/manage/input.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readText = readText;
+exports.loadInputFile = loadInputFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml_1 = require("yaml");
+const errors_1 = require("../errors");
+const stdin = () => fs.readFileSync(0, 'utf8');
+/** Reads a file (or stdin for "-") as raw text, turning I/O errors into usage errors. */
+function readText(file, readStdin = stdin) {
+    if (file === '-')
+        return readStdin().replace(/^\uFEFF/, '');
+    try {
+        return fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+    }
+    catch (err) {
+        throw new errors_1.CliError(`Cannot read ${file}: ${err.message}`);
+    }
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function structured(value, file) {
+    if (Array.isArray(value))
+        return { kind: 'array', value };
+    if (isPlainObject(value))
+        return { kind: 'object', value };
+    throw new errors_1.CliError(`${file} must contain an object or an array`);
+}
+function parseJson(raw, file) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new errors_1.CliError(`${file} is not valid JSON: ${err.message}`);
+    }
+}
+/** Markdown/text, with optional leading `---` YAML frontmatter. Never parsed as YAML otherwise. */
+function parseText(raw, file) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    if (!match)
+        return { kind: 'text', value: raw };
+    let front;
+    try {
+        front = (0, yaml_1.parse)(match[1]);
+    }
+    catch (err) {
+        throw new errors_1.CliError(`${file}: frontmatter is not valid YAML: ${err.message}`);
+    }
+    if (!isPlainObject(front))
+        throw new errors_1.CliError(`${file}: frontmatter must be a YAML mapping`);
+    return { kind: 'text', value: match[2].replace(/^\r?\n/, ''), frontmatter: front };
+}
+/**
+ * Loads a `-f` input. By extension: .json/.yaml/.yml → object or array, .jsonl → array,
+ * .md/.markdown/.txt → text (leading `---` frontmatter split off unless `frontmatter: false`). "-" reads stdin: JSON when it starts with { or [, otherwise text; always text with `stdinText: true`.
+ */
+function loadInputFile(file, readStdin = stdin, opts = {}) {
+    const text = (raw, name) => (opts.frontmatter === false ? { kind: 'text', value: raw } : parseText(raw, name));
+    const raw = readText(file, readStdin);
+    if (file === '-') {
+        const trimmed = raw.trimStart();
+        return !opts.stdinText && (trimmed.startsWith('{') || trimmed.startsWith('['))
+            ? structured(parseJson(raw, 'stdin'), 'stdin')
+            : text(raw, 'stdin');
+    }
+    const ext = path.extname(file).toLowerCase();
+    switch (ext) {
+        case '.json':
+            return structured(parseJson(raw, file), file);
+        case '.yaml':
+        case '.yml': {
+            let parsed;
+            try {
+                parsed = (0, yaml_1.parse)(raw);
+            }
+            catch (err) {
+                throw new errors_1.CliError(`${file} is not valid YAML: ${err.message}`);
+            }
+            return structured(parsed, file);
+        }
+        case '.jsonl':
+            return {
+                kind: 'array',
+                value: raw.split('\n').flatMap((line, i) => {
+                    if (!line.trim())
+                        return [];
+                    try {
+                        return [JSON.parse(line)];
+                    }
+                    catch (err) {
+                        throw new errors_1.CliError(`${file} line ${i + 1}: ${err.message}`);
+                    }
+                }),
+            };
+        case '.md':
+        case '.markdown':
+        case '.txt':
+            return text(raw, file);
+        default:
+            throw new errors_1.CliError(`Unsupported file type ${ext || '(none)'} for ${file}; use .json, .yaml, .yml, .jsonl, .md, .txt or - for stdin`);
+    }
+}

package/dist/manage/output.js

@@ -0,0 +1,127 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTable = renderTable;
+exports.writeOutput = writeOutput;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml_1 = require("yaml");
+const errors_1 = require("../errors");
+const PREFERRED = [
+    'id', 'external_id', 'prompt_external_id', 'skill_id', 'task_id', 'workflow_id', 'version',
+    'serial', 'slug', 'name', 'status', 'enabled', 'is_active', 'scope', 'created_at',
+];
+const MAX_CELL = 60;
+const isScalar = (v) => v === null || ['string', 'number', 'boolean'].includes(typeof v);
+function cell(value) {
+    const s = value === undefined || value === null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
+    const flat = s.replace(/\s+/g, ' ');
+    return flat.length > MAX_CELL ? `${flat.slice(0, MAX_CELL - 3)}...` : flat;
+}
+function renderTable(rows) {
+    const first = rows[0] ?? {};
+    let columns = PREFERRED.filter((c) => c in first).slice(0, 6);
+    if (columns.length === 0)
+        columns = Object.keys(first).filter((k) => isScalar(first[k])).slice(0, 4);
+    const cells = rows.map((r) => columns.map((c) => cell(r[c])));
+    const widths = columns.map((c, i) => Math.max(c.length, ...cells.map((r) => r[i].length)));
+    const line = (vals) => vals.map((v, i) => (i === vals.length - 1 ? v : v.padEnd(widths[i]))).join('  ');
+    return [line(columns), ...cells.map(line)].join('\n');
+}
+function asRecord(data) {
+    return typeof data === 'object' && data !== null && !Array.isArray(data) ? data : {};
+}
+async function writeFile(data, opts, file) {
+    const record = asRecord(data);
+    if (opts.downloadField) {
+        const url = record[opts.downloadField];
+        if (typeof url !== 'string')
+            throw new errors_1.CliError(`The result has no ${opts.downloadField} to download`, 1);
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new errors_1.CliError(`Download failed: HTTP ${res.status}`, 1);
+        const bytes = Buffer.from(await res.arrayBuffer());
+        fs.writeFileSync(file, bytes);
+        process.stderr.write(`Saved ${bytes.length} bytes to ${file}\n`);
+        return;
+    }
+    const ext = path.extname(file).toLowerCase();
+    let body;
+    if (ext === '.json')
+        body = `${JSON.stringify(data, null, 2)}\n`;
+    else if (ext === '.yaml' || ext === '.yml')
+        body = (0, yaml_1.stringify)(data);
+    else if (ext === '.md' || ext === '.markdown' || ext === '.txt') {
+        const text = opts.textField ? record[opts.textField] : undefined;
+        if (typeof text !== 'string')
+            throw new errors_1.CliError(`-o ${file}: this result has no text body; use .json or .yaml`);
+        const front = Object.fromEntries((opts.frontmatterKeys ?? []).filter((k) => record[k] !== undefined && record[k] !== null).map((k) => [k, record[k]]));
+        const head = Object.keys(front).length ? `---\n${(0, yaml_1.stringify)(front)}---\n\n` : '';
+        body = `${head}${text}`;
+    }
+    else {
+        throw new errors_1.CliError(`Unsupported output type ${ext || '(none)'} for ${file}; use .json, .yaml, .md or .txt`);
+    }
+    fs.writeFileSync(file, body);
+    process.stderr.write(`Wrote ${file}\n`);
+}
+/** Renders a tool result: -o file, --json, or a human table/YAML/text on stdout. */
+async function writeOutput(data, opts) {
+    if (opts.outFile)
+        return writeFile(data, opts, opts.outFile);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+        return;
+    }
+    const record = asRecord(data);
+    if (Object.keys(record).length === 1 && typeof record.text === 'string') {
+        process.stdout.write(record.text.endsWith('\n') ? record.text : `${record.text}\n`);
+        return;
+    }
+    const listKey = Array.isArray(record.items)
+        ? 'items'
+        : 'pagination' in record
+            ? Object.keys(record).find((k) => Array.isArray(record[k]))
+            : undefined;
+    const rows = Array.isArray(data) ? data : listKey ? record[listKey] : undefined;
+    if (rows) {
+        process.stdout.write(rows.length ? `${renderTable(rows)}\n` : '(none)\n');
+        const p = asRecord(record.pagination);
+        if (p.page !== undefined)
+            process.stderr.write(`page ${p.page}/${p.total_pages} (total ${p.total})\n`);
+        return;
+    }
+    process.stdout.write((0, yaml_1.stringify)(data));
+}

package/dist/manage/project.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProject = resolveProject;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml_1 = require("yaml");
+const errors_1 = require("../errors");
+/** --project, then METRIO_PROJECT, then `project:` in the nearest metrio.yaml walking up from cwd. */
+function resolveProject(flag, cwd = process.cwd()) {
+    if (flag)
+        return flag;
+    if (process.env.METRIO_PROJECT)
+        return process.env.METRIO_PROJECT;
+    let dir = path.resolve(cwd);
+    for (;;) {
+        const file = path.join(dir, 'metrio.yaml');
+        if (fs.existsSync(file)) {
+            let raw;
+            try {
+                raw = fs.readFileSync(file, 'utf8');
+            }
+            catch (err) {
+                throw new errors_1.CliError(`Cannot read ${file}: ${err.message}`);
+            }
+            let doc;
+            try {
+                doc = (0, yaml_1.parse)(raw);
+            }
+            catch (err) {
+                throw new errors_1.CliError(`${file} is not valid YAML: ${err.message}`);
+            }
+            if (doc && typeof doc.project === 'string' && doc.project)
+                return doc.project;
+            throw new errors_1.CliError(`${file} has no "project:" entry`);
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}

package/dist/manage/registry.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MANAGE_GROUPS = exports.COMMANDS = void 0;
+exports.findCommand = findCommand;
+exports.groupHelp = groupHelp;
+exports.commandHelp = commandHelp;
+const P = (prop, label) => ({ prop, label });
+const PROMPT = P('prompt_external_id', '<prompt-id>');
+const VERSION_ID = P('version_id', '<version-id>');
+const SKILL = P('skill_id', '<skill-id>');
+const WF = P('workflow_id', '<workflow-id>');
+const WF_VERSION = P('version', '<version>');
+const SCHEDULE = P('schedule_id', '<schedule-id>');
+const INSTANCE = P('mcp_instance_id', '<instance-id>');
+const TASK = P('task_id', '<task-id>');
+exports.COMMANDS = [
+    { path: ['project', 'list'], tool: 'list_projects', summary: 'List your projects' },
+    { path: ['project', 'create'], tool: 'create_project', summary: 'Create a project (-f or --team-id/--name)' },
+    { path: ['project', 'update'], tool: 'update_project', summary: 'Rename or describe the current project' },
+    { path: ['prompt', 'list'], tool: 'list_prompts', summary: 'List prompts' },
+    { path: ['prompt', 'create'], tool: 'create_prompt', summary: 'Create a prompt (--name)' },
+    { path: ['prompt', 'update'], tool: 'update_prompt', summary: 'Update a prompt', args: [PROMPT] },
+    { path: ['prompt', 'delete'], tool: 'delete_prompt', summary: 'Delete a prompt and all its versions', args: [PROMPT], destructive: true },
+    { path: ['prompt', 'skills'], tool: 'list_prompt_skills', summary: 'List skills attached to a prompt', args: [PROMPT] },
+    { path: ['prompt', 'skills', 'add'], tool: 'add_prompt_skill', summary: 'Attach a skill', args: [PROMPT, SKILL] },
+    { path: ['prompt', 'skills', 'remove'], tool: 'remove_prompt_skill', summary: 'Detach a skill', args: [PROMPT, SKILL] },
+    { path: ['prompt', 'mcps'], tool: 'list_prompt_mcps', summary: 'List MCP instances attached to a prompt', args: [PROMPT] },
+    { path: ['prompt', 'set-mcp-tools'], tool: 'set_prompt_mcp_tools', summary: 'Set the MCP tool allowlist (-f tools.yaml)', args: [PROMPT] },
+    { path: ['prompt', 'diff'], tool: 'diff_prompt', summary: 'Diff two versions', args: [PROMPT, P('from_serial', '<from>'), P('to_serial', '<to>')] },
+    { path: ['version', 'list'], tool: 'list_versions', summary: 'List versions of a prompt', args: [PROMPT] },
+    { path: ['version', 'get'], tool: 'get_version', summary: 'Get a version (-o v.yaml | system.md)', args: [VERSION_ID], textField: 'system_prompt' },
+    { path: ['version', 'create'], tool: 'create_version', summary: 'Create a version (-f system.md | v.yaml)', args: [PROMPT], textField: 'system_prompt' },
+    { path: ['version', 'update'], tool: 'update_version', summary: 'Update a version (-f system.md | v.yaml)', args: [VERSION_ID], textField: 'system_prompt' },
+    { path: ['version', 'create-batch'], tool: 'create_versions', summary: 'Create versions for several prompts (-f versions.jsonl)', wrap: 'versions' },
+    { path: ['skill', 'list'], tool: 'list_skills', summary: 'List skills' },
+    { path: ['skill', 'get'], tool: 'get_skill', summary: 'Get a skill (-o skill.md)', args: [SKILL], textField: 'content', frontmatterKeys: ['name', 'description', 'references'] },
+    { path: ['skill', 'create'], tool: 'create_skill', summary: 'Create a skill (-f skill.md)', textField: 'content', frontmatterKeys: ['name', 'description', 'references'] },
+    { path: ['skill', 'update'], tool: 'update_skill', summary: 'Update a skill (-f skill.md)', args: [SKILL], textField: 'content', frontmatterKeys: ['name', 'description', 'references'] },
+    { path: ['skill', 'delete'], tool: 'delete_skill', summary: 'Delete a skill', args: [SKILL], destructive: true },
+    { path: ['workflow', 'list'], tool: 'list_workflows', summary: 'List workflows' },
+    { path: ['workflow', 'get'], tool: 'get_workflow', summary: 'Get a workflow with its definition', args: [WF] },
+    { path: ['workflow', 'create'], tool: 'create_workflow', summary: 'Create a workflow (-f definition.json)', wrap: 'definition' },
+    { path: ['workflow', 'update'], tool: 'update_workflow', summary: 'Edit the live version (-f definition.json) or --enabled', args: [WF], wrap: 'definition' },
+    { path: ['workflow', 'delete'], tool: 'delete_workflow', summary: 'Delete a workflow', args: [WF], destructive: true },
+    { path: ['workflow', 'bump-pins'], tool: 'bump_prompt_pins', summary: 'Repoint prompt pins (-f pins.yaml)', args: [WF], wrap: 'pins' },
+    { path: ['workflow', 'version', 'list'], tool: 'list_workflow_versions', summary: 'List workflow versions', args: [WF] },
+    { path: ['workflow', 'version', 'get'], tool: 'get_workflow_version', summary: 'Get one workflow version', args: [WF, WF_VERSION] },
+    { path: ['workflow', 'version', 'create'], tool: 'create_workflow_version', summary: 'Create a version (-f definition.json)', args: [WF], wrap: 'definition' },
+    { path: ['workflow', 'version', 'diff'], tool: 'diff_workflow_version', summary: 'Diff two workflow versions', args: [WF, P('from_version', '<from>'), P('to_version', '<to>')] },
+    { path: ['workflow', 'version', 'publish'], tool: 'publish_workflow_version', summary: 'Publish a draft (--activate to go live)', args: [WF, WF_VERSION] },
+    { path: ['workflow', 'version', 'activate'], tool: 'set_active_workflow_version', summary: 'Make a published version live (rollback too)', args: [WF, WF_VERSION] },
+    { path: ['schedule', 'list'], tool: 'list_schedules', summary: 'List schedules' },
+    { path: ['schedule', 'create'], tool: 'create_schedule', summary: 'Create a schedule (-f schedule.yaml)' },
+    { path: ['schedule', 'update'], tool: 'update_schedule', summary: 'Update a schedule (-f schedule.yaml)', args: [SCHEDULE] },
+    { path: ['schedule', 'delete'], tool: 'delete_schedule', summary: 'Delete a schedule', args: [SCHEDULE], destructive: true },
+    { path: ['mcp', 'list'], tool: 'list_mcp_instances', summary: 'List MCP instances' },
+    { path: ['mcp', 'tools'], tool: 'list_mcp_instance_tools', summary: 'List tools of an MCP instance', args: [INSTANCE] },
+    { path: ['mcp', 'create'], tool: 'create_mcp_instance', summary: 'Create an MCP instance (-f instance.yaml)' },
+    { path: ['mcp', 'update'], tool: 'update_mcp_instance', summary: 'Update an MCP instance (-f instance.yaml)', args: [INSTANCE] },
+    { path: ['run', 'list'], tool: 'list_runs', summary: 'List execution runs' },
+    { path: ['run', 'trace'], tool: 'get_task_trace', summary: 'Call trace for one task', args: [TASK] },
+    { path: ['run', 'workflow', 'list'], tool: 'list_workflow_runs', summary: 'List workflow runs' },
+    { path: ['run', 'workflow', 'get'], tool: 'get_workflow_run', summary: 'Get one workflow run', args: [TASK] },
+    { path: ['run', 'workflow', 'attachment'], tool: 'get_workflow_run_attachment', summary: 'Download a run attachment (-o file)', args: [TASK, P('key', '<key>')], downloadField: 'url' },
+    { path: ['admin', 'model', 'list'], tool: 'list_models', summary: 'List models (admin)' },
+    { path: ['admin', 'model', 'create'], tool: 'create_model', summary: 'Create a model (admin, -f model.yaml)' },
+    { path: ['admin', 'model', 'update'], tool: 'update_model', summary: 'Update a model (admin)', args: [P('model_id', '<model-id>')] },
+    { path: ['admin', 'mcp-def', 'list'], tool: 'list_mcp_server_definitions', summary: 'List MCP server definitions (admin)' },
+    { path: ['admin', 'mcp-def', 'create'], tool: 'create_mcp_server_definition', summary: 'Register an MCP server (admin, -f def.yaml)' },
+    { path: ['model-tiers'], tool: 'list_model_tiers', summary: 'List model tiers' },
+];
+exports.MANAGE_GROUPS = Array.from(new Set(exports.COMMANDS.map((c) => c.path[0])));
+/** Longest command path that prefixes argv. */
+function findCommand(argv) {
+    let best;
+    for (const spec of exports.COMMANDS) {
+        if (spec.path.every((word, i) => argv[i] === word) && (!best || spec.path.length > best.path.length))
+            best = spec;
+    }
+    return best ? { spec: best, rest: argv.slice(best.path.length) } : undefined;
+}
+const usage = (spec) => ['metrio', ...spec.path, ...(spec.args ?? []).map((a) => a.label)].join(' ');
+function groupHelp(group) {
+    const specs = exports.COMMANDS.filter((c) => c.path[0] === group);
+    const width = Math.max(...specs.map((s) => usage(s).length));
+    return [
+        `metrio ${group} - manage ${group} resources (console login)`,
+        '',
+        ...specs.map((s) => `  ${usage(s).padEnd(width)}  ${s.summary}`),
+        '',
+        'Run "metrio <command> --help" for its options.',
+        '',
+    ].join('\n');
+}
+function commandHelp(spec) {
+    const lines = [
+        `${usage(spec)} - ${spec.summary}`,
+        '',
+        `Calls the console tool ${spec.tool}. Every input field of that tool can be passed as --<field-name>`,
+        '(kebab-case; see "metrio tools --json"). Text fields take @file (start with @@ for a literal @); object/array fields take JSON or @file.',
+        '',
+        'Options:',
+        '  -f, --file <path>   Input: .json/.yaml/.yml (fields), .jsonl (list), .md/.txt (text), - (stdin)',
+        '  -o, --output <path> Write the result: .json, .yaml, .md/.txt',
+        '      --json          Print the raw result as JSON',
+        '      --project <slug> Project (default: METRIO_PROJECT or metrio.yaml)',
+    ];
+    if (spec.destructive)
+        lines.push('      --yes           Confirm the delete');
+    if (spec.textField)
+        lines.push('', `A .md/.txt file fills ${spec.textField}.`);
+    if (spec.frontmatterKeys)
+        lines.push(`Its YAML frontmatter may set: ${spec.frontmatterKeys.join(', ')}.`);
+    if (spec.wrap)
+        lines.push('', `A file without a "${spec.wrap}" key is sent as ${spec.wrap}.`);
+    if (spec.downloadField)
+        lines.push('', '-o downloads the file itself.');
+    return `${lines.join('\n')}\n`;
+}

package/dist/manage/run.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runManageCommand = runManageCommand;
+const client_1 = require("../console/client");
+const errors_1 = require("../errors");
+const input_1 = require("./input");
+const output_1 = require("./output");
+const project_1 = require("./project");
+const registry_1 = require("./registry");
+const workspace_1 = require("../sync/workspace");
+const schema_1 = require("./schema");
+function parse(rest) {
+    const parsed = { tokens: [], json: false, yes: false };
+    const take = (i, name) => {
+        const v = rest[i + 1];
+        if (v === undefined)
+            throw new errors_1.CliError(`${name} needs a value`);
+        return v;
+    };
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        const opt = /^--(file|output|project)=(.*)$/s.exec(arg);
+        if (opt) {
+            if (opt[1] === 'file')
+                parsed.file = opt[2];
+            else if (opt[1] === 'output')
+                parsed.outFile = opt[2];
+            else
+                parsed.project = opt[2];
+        }
+        else if (arg === '-f' || arg === '--file')
+            parsed.file = take(i++, arg);
+        else if (arg === '-o' || arg === '--output')
+            parsed.outFile = take(i++, arg);
+        else if (arg === '--project')
+            parsed.project = take(i++, arg);
+        else if (arg === '--json')
+            parsed.json = true;
+        else if (arg === '--yes')
+            parsed.yes = true;
+        else if (arg.startsWith('--')) {
+            const eq = arg.indexOf('=');
+            parsed.tokens.push(eq === -1 ? { flag: arg.slice(2) } : { flag: arg.slice(2, eq), value: arg.slice(eq + 1) });
+        }
+        else
+            parsed.tokens.push({ positional: arg });
+    }
+    return parsed;
+}
+function fromFile(spec, file, readStdin) {
+    const loaded = (0, input_1.loadInputFile)(file, readStdin, { frontmatter: !!spec.frontmatterKeys, stdinText: !!spec.textField });
+    const cmd = `metrio ${spec.path.join(' ')}`;
+    if (loaded.kind === 'text') {
+        if (!spec.textField)
+            throw new errors_1.CliError(`${cmd} does not take a text file; use .json or .yaml`);
+        return { ...(loaded.frontmatter ?? {}), [spec.textField]: loaded.value };
+    }
+    if (loaded.kind === 'array') {
+        if (!spec.wrap)
+            throw new errors_1.CliError(`${file} holds a list; ${cmd} takes an object`);
+        return { [spec.wrap]: loaded.value };
+    }
+    return spec.wrap && !(spec.wrap in loaded.value) ? { [spec.wrap]: loaded.value } : loaded.value;
+}
+/** True when the non-option words are a proper prefix of some command path, e.g. `workflow version`. */
+function isCommandPrefix(argv) {
+    const words = argv.filter((a) => !a.startsWith('-'));
+    return registry_1.COMMANDS.some((c) => words.length < c.path.length && words.every((w, i) => c.path[i] === w));
+}
+/**
+ * A prompt positional may name a tracked directory (prompts/<dir> or <dir>) instead of the
+ * numeric id — only for the workspace's own project, since ids are per project.
+ */
+function promptRef(raw, project) {
+    if (/^\d+$/.test(raw))
+        return raw;
+    const root = (0, workspace_1.findRoot)();
+    const dir = raw.replace(/\/+$/, '');
+    const key = dir.startsWith('prompts/') ? dir : `prompts/${dir}`;
+    // A broken workspace surfaces its own (informative) CliError.
+    const workspaceProject = root ? (0, workspace_1.readProject)(root) : undefined;
+    const entry = root ? (0, workspace_1.readState)(root, workspaceProject).resources[key] : undefined;
+    if (!entry || entry.kind !== 'prompt') {
+        throw new errors_1.CliError(`Unknown prompt "${raw}": use the numeric id, or a prompts/<dir> tracked in .metrio/state.json`);
+    }
+    if (project !== undefined && project !== workspaceProject) {
+        throw new errors_1.CliError(`"${raw}" is a directory of project ${workspaceProject}, but this command targets project ${String(project)}`);
+    }
+    return entry.id;
+}
+/** Runs one registry command; argv starts with the group, e.g. ['version', 'create', '12', '-f', 's.md']. */
+async function runManageCommand(argv, readStdin) {
+    const match = (0, registry_1.findCommand)(argv);
+    const wantsHelp = argv.includes('-h') || argv.includes('--help');
+    if (!match || wantsHelp) {
+        if (match)
+            process.stdout.write((0, registry_1.commandHelp)(match.spec));
+        else if (wantsHelp || argv.length === 1 || isCommandPrefix(argv))
+            process.stdout.write((0, registry_1.groupHelp)(argv[0]));
+        else
+            throw new errors_1.CliError(`Unknown command: metrio ${argv.slice(0, 2).join(' ')}. Run "metrio ${argv[0]} --help".`);
+        return;
+    }
+    const { spec, rest } = match;
+    const opts = parse(rest);
+    const client = new client_1.ConsoleClient(await (0, client_1.resolveConsoleAuth)());
+    const tool = (await client.listTools()).find((t) => t.name === spec.tool);
+    if (!tool) {
+        throw new errors_1.CliError(`Your login cannot use ${spec.tool} (it needs a scope your login does not have, or the console is older than this CLI). Try "metrio login" again.`, 3);
+    }
+    const schema = tool.inputSchema;
+    const props = schema.properties ?? {};
+    const { values, positionals } = (0, schema_1.resolveFlags)(opts.tokens, schema, readStdin);
+    const expected = spec.args ?? [];
+    if (positionals.length !== expected.length) {
+        const labels = expected.map((a) => a.label).join(' ') || 'no arguments';
+        throw new errors_1.CliError(`metrio ${spec.path.join(' ')} expects ${labels}, got ${positionals.length ? positionals.join(' ') : 'none'}`);
+    }
+    const args = {};
+    const sources = {};
+    const put = (key, value, source) => {
+        args[key] = value;
+        sources[key] = source;
+    };
+    if (opts.file)
+        for (const [k, v] of Object.entries(fromFile(spec, opts.file, readStdin)))
+            put(k, v, `file ${opts.file}`);
+    if (opts.project && 'project_slug' in props)
+        put('project_slug', opts.project, 'project');
+    for (const [k, v] of Object.entries(values))
+        put(k, v, `--${(0, schema_1.kebab)(k)}`);
+    // A prompt directory resolves against the final project_slug, so it waits for it.
+    let promptDir;
+    expected.forEach((arg, i) => {
+        if (arg.prop === 'prompt_external_id' && !/^\d+$/.test(positionals[i]))
+            promptDir = { prop: arg.prop, raw: positionals[i], label: arg.label };
+        else
+            put(arg.prop, (0, schema_1.coercePositional)(positionals[i], props[arg.prop], arg.label), arg.label);
+    });
+    if ('project_slug' in props && !opts.project && args.project_slug === undefined) {
+        try {
+            const project = (0, project_1.resolveProject)(undefined);
+            if (project)
+                put('project_slug', project, 'project');
+        }
+        catch (err) {
+            if ((schema.required ?? []).includes('project_slug') || !(err instanceof errors_1.CliError))
+                throw err;
+        }
+    }
+    if (promptDir) {
+        put(promptDir.prop, (0, schema_1.coercePositional)(promptRef(promptDir.raw, args.project_slug), props[promptDir.prop], promptDir.label), promptDir.label);
+    }
+    if ((schema.required ?? []).includes('project_slug') && args.project_slug === undefined) {
+        throw new errors_1.CliError('No project. Pass --project <slug>, set METRIO_PROJECT, or add "project: <slug>" to metrio.yaml.');
+    }
+    const { args: accepted, dropped } = (0, schema_1.dropUnaccepted)(args, schema);
+    if (dropped.length)
+        process.stderr.write(`metrio: ignoring fields ${spec.tool} does not accept: ${dropped.join(', ')}\n`);
+    (0, schema_1.validateArgs)(spec.tool, accepted, schema, sources);
+    if (spec.destructive && !opts.yes) {
+        process.stderr.write(`About to run ${spec.tool} with ${JSON.stringify(accepted)}.\n`);
+        throw new errors_1.CliError('Re-run with --yes to confirm.', 2);
+    }
+    const data = await client.callTool(spec.tool, accepted, { retry: tool.scope === 'read' });
+    await (0, output_1.writeOutput)(data, {
+        json: opts.json,
+        outFile: opts.outFile,
+        textField: spec.textField,
+        frontmatterKeys: spec.frontmatterKeys,
+        downloadField: spec.downloadField,
+    });
+    if (isRecord(data) && data.valid === false) {
+        const errors = Array.isArray(data.errors) ? data.errors : [];
+        const first = errors.length ? (typeof errors[0] === 'string' ? errors[0] : JSON.stringify(errors[0])) : 'no details';
+        const detail = errors.length > 1 ? `${first} (+${errors.length - 1} more)` : first;
+        throw new errors_1.CliError(`metrio: ${spec.tool} reported invalid input: ${detail}`, 2);
+    }
+    if (isRecord(data) && data.all_succeeded === false) {
+        const failed = Array.isArray(data.failed) ? data.failed.length : 0;
+        const total = failed + (Array.isArray(data.created) ? data.created.length : 0);
+        throw new errors_1.CliError(`metrio: ${spec.tool}: ${failed} of ${total} items failed`, 1);
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);