@metrio-ai/cli 1.3.1 → 1.4.0

package/README.md

@@ -31,6 +31,8 @@ metrio prompt list
 metrio version get 34 -o system.md          # the system prompt as a file
 metrio version create 12 -f system.md --model-provider openai --model-name gpt-5
 metrio version get 34 -o v.yaml && metrio version update 34 -f v.yaml   # round-trip
+metrio version get 34 -o greeter.md --frontmatter    # settings as YAML frontmatter + the prompt verbatim
+metrio version create 12 -f greeter.md --frontmatter # one file carries the whole version
 metrio skill get 5 -o skill.md              # frontmatter (name, description, references) + body
 metrio skill update 5 -f skill.md
 metrio workflow version create intake -f definition.json --activate

package/dist/manage/output.js

@@ -87,7 +87,9 @@ async function writeFile(data, opts, file) {
         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 front = Object.fromEntries((opts.frontmatterKeys ?? [])
+            .filter((k) => record[k] !== undefined && (record[k] !== null || (opts.frontmatterKeepNull ?? []).includes(k)))
+            .map((k) => [k, record[k]]));
         const head = Object.keys(front).length ? `---\n${(0, yaml_1.stringify)(front)}---\n\n` : '';
         body = `${head}${text}`;
     }

package/dist/manage/registry.js

@@ -1,10 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MANAGE_GROUPS = exports.COMMANDS = void 0;
+exports.MANAGE_GROUPS = exports.COMMANDS = exports.READ_ONLY_FRONTMATTER = void 0;
 exports.findCommand = findCommand;
 exports.groupHelp = groupHelp;
 exports.commandHelp = commandHelp;
 const P = (prop, label) => ({ prop, label });
+/** Identity of the version a file came from: written for reference, never sent back. */
+exports.READ_ONLY_FRONTMATTER = ['version_id', 'serial'];
+const VERSION_FRONTMATTER = [
+    ...exports.READ_ONLY_FRONTMATTER, 'description', 'tier_key', 'model_provider', 'model_name',
+    'output_format', 'model_settings', 'model_fallbacks', 'output_schema',
+];
+/** get_version → the create_version/update_version field names the frontmatter uses. */
+function versionFrontmatterView(r) {
+    const tier = r.model_tier?.tier_key;
+    // A file describes the whole version: "no schema" / "no fallbacks" are written explicitly, so
+    // update -f clears them instead of keeping what the target version had (omission keeps).
+    const view = {
+        ...r,
+        version_id: r.id,
+        output_schema: r.output_schema ?? null,
+        model_fallbacks: r.model_fallbacks ?? [],
+    };
+    if (typeof tier === 'string' && tier) {
+        view.tier_key = tier;
+        delete view.model_provider;
+        delete view.model_name;
+    }
+    return view;
+}
+const VERSION_FILE = {
+    optionalFrontmatterKeys: VERSION_FRONTMATTER,
+    frontmatterView: versionFrontmatterView,
+    frontmatterKeepNull: ['output_schema'],
+};
 const PROMPT = P('prompt_external_id', '<prompt-id>');
 const VERSION_ID = P('version_id', '<version-id>');
 const SKILL = P('skill_id', '<skill-id>');
@@ -28,9 +57,9 @@ exports.COMMANDS = [
     { 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', 'get'], tool: 'get_version', summary: 'Get a version (-o v.yaml | system.md [--frontmatter])', args: [VERSION_ID], textField: 'system_prompt', ...VERSION_FILE },
+    { path: ['version', 'create'], tool: 'create_version', summary: 'Create a version (-f system.md [--frontmatter] | v.yaml)', args: [PROMPT], textField: 'system_prompt', ...VERSION_FILE },
+    { path: ['version', 'update'], tool: 'update_version', summary: 'Update a version (-f system.md [--frontmatter] | v.yaml)', args: [VERSION_ID], textField: 'system_prompt', ...VERSION_FILE },
     { 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'] },
@@ -107,10 +136,16 @@ function commandHelp(spec) {
     ];
     if (spec.destructive)
         lines.push('      --yes           Confirm the delete');
+    if (spec.optionalFrontmatterKeys) {
+        lines.push('      --frontmatter   .md files carry the version settings as YAML frontmatter (see below)');
+    }
     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.optionalFrontmatterKeys) {
+        lines.push(`With --frontmatter, a .md file starts with YAML frontmatter (${spec.optionalFrontmatterKeys.join(', ')})`, `and the rest is ${spec.textField} verbatim. ${exports.READ_ONLY_FRONTMATTER.join(' and ')} are written by -o and ignored by -f.`, 'Without --frontmatter the whole file is the text, so a prompt that starts with --- stays intact.');
+    }
     if (spec.wrap)
         lines.push('', `A file without a "${spec.wrap}" key is sent as ${spec.wrap}.`);
     if (spec.downloadField)

package/dist/manage/run.js

@@ -10,7 +10,7 @@ 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 parsed = { tokens: [], json: false, yes: false, frontmatter: false };
     const take = (i, name) => {
         const v = rest[i + 1];
         if (v === undefined)
@@ -38,6 +38,8 @@ function parse(rest) {
             parsed.json = true;
         else if (arg === '--yes')
             parsed.yes = true;
+        else if (arg === '--frontmatter')
+            parsed.frontmatter = 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) });
@@ -47,13 +49,17 @@ function parse(rest) {
     }
     return parsed;
 }
-function fromFile(spec, file, readStdin) {
-    const loaded = (0, input_1.loadInputFile)(file, readStdin, { frontmatter: !!spec.frontmatterKeys, stdinText: !!spec.textField });
+function fromFile(spec, file, frontmatter, readStdin) {
+    const loaded = (0, input_1.loadInputFile)(file, readStdin, { frontmatter: !!spec.frontmatterKeys || frontmatter, 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 };
+        const front = { ...(loaded.frontmatter ?? {}) };
+        if (frontmatter)
+            for (const key of registry_1.READ_ONLY_FRONTMATTER)
+                delete front[key];
+        return { ...front, [spec.textField]: loaded.value };
     }
     if (loaded.kind === 'array') {
         if (!spec.wrap)
@@ -103,6 +109,9 @@ async function runManageCommand(argv, readStdin) {
     }
     const { spec, rest } = match;
     const opts = parse(rest);
+    if (opts.frontmatter && !spec.optionalFrontmatterKeys) {
+        throw new errors_1.CliError(`--frontmatter only applies to metrio version get | create | update, not metrio ${spec.path.join(' ')}`);
+    }
     const client = new client_1.ConsoleClient(await (0, client_1.resolveConsoleAuth)());
     const tool = (await client.listTools()).find((t) => t.name === spec.tool);
     if (!tool) {
@@ -123,12 +132,18 @@ async function runManageCommand(argv, readStdin) {
         sources[key] = source;
     };
     if (opts.file)
-        for (const [k, v] of Object.entries(fromFile(spec, opts.file, readStdin)))
+        for (const [k, v] of Object.entries(fromFile(spec, opts.file, opts.frontmatter, 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 version uses a tier OR a specific model, and the console lets tier_key win when both are
+    // sent; so a model chosen by flag must drop a tier that came from the file, or the flag is ignored.
+    if (('model_provider' in values || 'model_name' in values) && !('tier_key' in values) && 'tier_key' in args) {
+        delete args.tier_key;
+        delete sources.tier_key;
+    }
     // A prompt directory resolves against the final project_slug, so it waits for it.
     let promptDir;
     expected.forEach((arg, i) => {
@@ -163,11 +178,14 @@ async function runManageCommand(argv, readStdin) {
         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, {
+    const textOut = !!opts.outFile && /\.(md|markdown|txt)$/i.test(opts.outFile);
+    const withFrontmatter = opts.frontmatter && textOut && isRecord(data) && spec.frontmatterView;
+    await (0, output_1.writeOutput)(withFrontmatter ? spec.frontmatterView(data) : data, {
         json: opts.json,
         outFile: opts.outFile,
         textField: spec.textField,
-        frontmatterKeys: spec.frontmatterKeys,
+        frontmatterKeys: spec.frontmatterKeys ?? (opts.frontmatter ? spec.optionalFrontmatterKeys : undefined),
+        frontmatterKeepNull: withFrontmatter ? spec.frontmatterKeepNull : undefined,
         downloadField: spec.downloadField,
     });
     if (isRecord(data) && data.valid === false) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metrio-ai/cli",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "packageManager": "yarn@4.14.1",
   "description": "Metrio AI command-line interface: run prompts and workflows, manage Metrio resources",
   "bin": {