@spendgraph/cli 0.2.0

package/dist/commands/dashboard.js

@@ -0,0 +1,236 @@
+import { UsageError } from "../errors.js";
+const range = (ctx) => ({
+    ...ctx.scope(),
+    from: ctx.flag("from"),
+    to: ctx.flag("to"),
+});
+function events(ctx) {
+    const body = ctx.body({});
+    const list = Array.isArray(body.events) ? body.events : undefined;
+    if (!list)
+        throw new UsageError("--file must hold { events: [...] }.");
+    return list;
+}
+/** Projects, their budgets and who is in them. */
+export const projects = {
+    name: "project",
+    summary: "projects, budgets and members",
+    commands: [
+        { name: "list", summary: "every project you can see", run: (ctx) => ctx.sg.projects.list() },
+        {
+            name: "create",
+            summary: "a new project",
+            run: (ctx) => ctx.sg.projects.create({ name: ctx.flag("name") ?? ctx.need(0, "name") }),
+        },
+        {
+            name: "budget",
+            summary: "what the project is allowed to spend",
+            usage: "<projectId>",
+            run: (ctx) => ctx.sg.projects.budget(ctx.need(0, "projectId")),
+        },
+        {
+            name: "set-budget",
+            summary: "change the budget, from flags or --file",
+            usage: "<projectId>",
+            run: (ctx) => ctx.sg.projects.setBudget(ctx.need(0, "projectId"), ctx.body({ limitMicros: ctx.num("limit-micros") })),
+        },
+        {
+            name: "members",
+            summary: "who is in the project",
+            usage: "<projectId>",
+            run: (ctx) => ctx.sg.projects.members(ctx.need(0, "projectId")),
+        },
+        {
+            name: "add-member",
+            summary: "add someone, from flags or --file",
+            usage: "<projectId>",
+            run: (ctx) => ctx.sg.projects.addMember(ctx.need(0, "projectId"), ctx.body({ userId: ctx.flag("user"), role: ctx.flag("role") })),
+        },
+        {
+            name: "remove-member",
+            summary: "take someone out",
+            usage: "<projectId> <userId>",
+            run: (ctx) => ctx.sg.projects.removeMember(ctx.need(0, "projectId"), ctx.need(1, "userId")),
+        },
+        {
+            name: "invite",
+            summary: "invite someone by email",
+            usage: "<projectId>",
+            run: (ctx) => ctx.sg.projects.invite(ctx.need(0, "projectId"), ctx.body({ email: ctx.flag("email"), role: ctx.flag("role") })),
+        },
+        {
+            name: "revoke-invite",
+            summary: "withdraw an invite",
+            usage: "<projectId> <inviteId>",
+            run: (ctx) => ctx.sg.projects.revokeInvite(ctx.need(0, "projectId"), ctx.need(1, "inviteId")),
+        },
+        {
+            name: "invite-preview",
+            summary: "what an invite token points at",
+            usage: "<token>",
+            run: (ctx) => ctx.sg.invites.preview(ctx.need(0, "token")),
+        },
+        {
+            name: "invite-accept",
+            summary: "accept an invite",
+            usage: "<token>",
+            run: (ctx) => ctx.sg.invites.accept(ctx.need(0, "token")),
+        },
+    ],
+};
+/** API keys. Minting one needs a dashboard session, never a key. */
+export const keys = {
+    name: "key",
+    summary: "api keys (session only)",
+    commands: [
+        {
+            name: "list",
+            summary: "every key in the project",
+            run: (ctx) => ctx.sg.keys.list(ctx.scope()),
+        },
+        {
+            name: "create",
+            summary: "mint a key; the plaintext is shown once and never again",
+            run: (ctx) => ctx.sg.keys.create({
+                projectId: ctx.project(),
+                name: ctx.flag("name") ?? ctx.need(0, "name"),
+            }),
+        },
+        {
+            name: "revoke",
+            summary: "revoke a key",
+            usage: "<keyId>",
+            run: (ctx) => ctx.sg.keys.revoke(ctx.need(0, "keyId")),
+        },
+    ],
+};
+/** Provider keys the server calls out with. Session only, deliberately. */
+export const credentials = {
+    name: "credential",
+    summary: "provider keys the server holds (session only)",
+    commands: [
+        { name: "list", summary: "which providers are set", run: (ctx) => ctx.sg.credentials.list() },
+        {
+            name: "set",
+            summary: "store a provider key",
+            run: (ctx) => ctx.sg.credentials.set({
+                provider: ctx.flag("provider") ?? ctx.need(0, "provider"),
+                apiKey: ctx.flag("key") ?? ctx.need(1, "key"),
+            }),
+        },
+        {
+            name: "remove",
+            summary: "forget a provider key",
+            usage: "<provider>",
+            run: (ctx) => ctx.sg.credentials.remove(ctx.need(0, "provider")),
+        },
+    ],
+};
+/** What a model costs, and what the catalogue knows. */
+export const pricing = {
+    name: "pricing",
+    summary: "model prices, coverage and the catalogue",
+    commands: [
+        { name: "list", summary: "every price row", run: (ctx) => ctx.sg.pricing.list() },
+        {
+            name: "override",
+            summary: "set your own price for a model, from --file",
+            usage: "<model>",
+            run: (ctx) => ctx.sg.pricing.override(ctx.need(0, "model"), ctx.body({})),
+        },
+        {
+            name: "coverage",
+            summary: "which models have a price",
+            run: (ctx) => ctx.sg.pricing.coverage(),
+        },
+        {
+            name: "readiness",
+            summary: "whether pricing is usable",
+            run: (ctx) => ctx.sg.pricing.readiness(),
+        },
+        {
+            name: "sync",
+            summary: "refresh from upstream",
+            run: (ctx) => ctx.sg.pricing.sync(ctx.body({})),
+        },
+        {
+            name: "models",
+            summary: "the model catalogue",
+            run: (ctx) => ctx.sg.models.list({ creator: ctx.flag("creator"), limit: ctx.num("limit") }),
+        },
+        {
+            name: "offers",
+            summary: "who serves a model, and at what price",
+            run: (ctx) => ctx.sg.models.offers({ model: ctx.flag("model"), q: ctx.flag("q") }),
+        },
+        {
+            name: "compare",
+            summary: "price one workload across models or providers",
+            run: (ctx) => ctx.sg.models.compare({
+                models: ctx.flag("models"),
+                offers: ctx.flag("offers"),
+                baseline: ctx.flag("baseline"),
+                benchmark: ctx.flag("benchmark"),
+                in: ctx.num("in"),
+                out: ctx.num("out"),
+                requests: ctx.num("requests"),
+            }),
+        },
+    ],
+};
+/** What was spent, by whom, on what. */
+export const spend = {
+    name: "spend",
+    summary: "usage, stats, events and alerts",
+    commands: [
+        { name: "summary", summary: "the totals", run: (ctx) => ctx.sg.stats.summary(range(ctx)) },
+        {
+            name: "timeseries",
+            summary: "spend over time",
+            run: (ctx) => ctx.sg.stats.timeseries({
+                ...range(ctx),
+                bucket: ctx.flag("bucket"),
+            }),
+        },
+        {
+            name: "by-model",
+            summary: "spend per model",
+            run: (ctx) => ctx.sg.stats.byModel(range(ctx)),
+        },
+        { name: "by-key", summary: "spend per api key", run: (ctx) => ctx.sg.stats.byKey(range(ctx)) },
+        {
+            name: "by-tag",
+            summary: "spend per tag",
+            run: (ctx) => ctx.sg.stats.byTag({ ...range(ctx), key: ctx.flag("key") }),
+        },
+        {
+            name: "events",
+            summary: "individual usage events",
+            run: (ctx) => ctx.sg.events.list({
+                ...range(ctx),
+                model: ctx.flag("model"),
+                key: ctx.flag("key"),
+                q: ctx.flag("q"),
+                sort: ctx.flag("sort"),
+                limit: ctx.num("limit"),
+                cursor: ctx.flag("cursor"),
+                format: ctx.flag("format"),
+            }),
+        },
+        {
+            name: "alerts",
+            summary: "budget alerts that have fired",
+            run: (ctx) => ctx.sg.alerts.list({ ...ctx.scope(), limit: ctx.num("limit") }),
+        },
+        {
+            name: "ingest",
+            summary: "post usage events from --file, and say what went unpriced",
+            run: (ctx) => ctx.sg.ingest.report(events(ctx)),
+        },
+        {
+            name: "playground",
+            summary: "run a one-off call server-side, from --file",
+            run: (ctx) => ctx.sg.playground.run(ctx.body({})),
+        },
+    ],
+};

package/dist/commands/prompts.d.ts

@@ -0,0 +1,3 @@
+import type { Group } from "../types.js";
+/** Stored prompts: writing them, versioning them, running them and reading what they cost. */
+export declare const prompts: Group;

package/dist/commands/prompts.js

@@ -0,0 +1,133 @@
+import { scoped } from "../context.js";
+import { UsageError } from "../errors.js";
+const saved = (ctx) => scoped(ctx, ctx.body({
+    name: ctx.flag("name"),
+    question: ctx.flag("question"),
+    models: ctx.list("models"),
+    temperature: ctx.num("temperature"),
+    maxTokens: ctx.num("max-tokens"),
+}));
+function cases(ctx) {
+    const body = ctx.body({});
+    const list = body.cases;
+    if (!Array.isArray(list))
+        throw new UsageError("--file must hold { cases: [...] }.");
+    return list;
+}
+/** Stored prompts: writing them, versioning them, running them and reading what they cost. */
+export const prompts = {
+    name: "prompt",
+    summary: "stored prompts, their versions, datasets and rollouts",
+    commands: [
+        {
+            name: "list",
+            summary: "every prompt in the project",
+            run: (ctx) => ctx.sg.prompts.list({
+                ...ctx.scope(),
+                limit: ctx.num("limit"),
+                cursor: ctx.flag("cursor"),
+                archived: ctx.bool("archived") || undefined,
+            }),
+        },
+        {
+            name: "get",
+            summary: "one prompt with its current version",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.prompts.get(ctx.need(0, "promptId"), { ...ctx.scope(), runs: ctx.num("runs") }),
+        },
+        {
+            name: "create",
+            summary: "write a new prompt",
+            run: (ctx) => ctx.sg.prompts.create(saved(ctx)),
+        },
+        {
+            name: "update",
+            summary: "write a new version of a prompt",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.prompts.update(ctx.need(0, "promptId"), saved(ctx), ctx.scope()),
+        },
+        {
+            name: "versions",
+            summary: "every stored version",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.prompts.versions(ctx.need(0, "promptId"), {
+                ...ctx.scope(),
+                limit: ctx.num("limit"),
+                origin: ctx.flag("origin"),
+            }),
+        },
+        {
+            name: "promote",
+            summary: "make a stored version the current one",
+            usage: "<promptId> <versionId>",
+            run: (ctx) => ctx.sg.prompts.promote(ctx.need(0, "promptId"), ctx.need(1, "versionId"), ctx.scope()),
+        },
+        {
+            name: "cases",
+            summary: "the evaluation dataset",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.prompts.cases(ctx.need(0, "promptId"), ctx.scope()),
+        },
+        {
+            name: "put-cases",
+            summary: "replace the evaluation dataset from --file",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.prompts.putCases(ctx.need(0, "promptId"), cases(ctx), ctx.scope()),
+        },
+        {
+            name: "rollouts",
+            summary: "what the prompt has been run for, and what it cost",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.prompts.rollouts(ctx.need(0, "promptId"), {
+                ...ctx.scope(),
+                limit: ctx.num("limit"),
+                cursor: ctx.flag("cursor"),
+                evaluation: ctx.bool("evaluation") || undefined,
+            }),
+        },
+        {
+            name: "report",
+            summary: "record a rollout run elsewhere, from --file",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.prompts.report(ctx.need(0, "promptId"), ctx.body({}), ctx.scope()),
+        },
+        {
+            name: "run",
+            summary: "run the prompt server-side",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.prompts.run(ctx.need(0, "promptId"), ctx.body({
+                model: ctx.flag("model"),
+                variables: undefined,
+            }), ctx.scope()),
+        },
+        {
+            name: "publish",
+            summary: "publish a draft",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.promptsAdmin.publish(ctx.need(0, "promptId"), ctx.body({})),
+        },
+        {
+            name: "archive",
+            summary: "take a prompt out of the list",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.promptsAdmin.archive(ctx.need(0, "promptId"), ctx.scope()),
+        },
+        {
+            name: "assay",
+            summary: "start an optimization run; --file must carry the budget",
+            usage: "<promptId>",
+            run: (ctx) => ctx.sg.promptsAdmin.assay(ctx.need(0, "promptId"), ctx.body({})),
+        },
+        {
+            name: "assays",
+            summary: "optimization runs in the project",
+            run: (ctx) => ctx.sg.promptsAdmin.runs({ ...ctx.scope(), limit: ctx.num("limit") }),
+        },
+        {
+            name: "assay-get",
+            summary: "one optimization run",
+            usage: "<runId>",
+            run: (ctx) => ctx.sg.promptsAdmin.run(ctx.need(0, "runId")),
+        },
+    ],
+};

package/dist/commands/skills.d.ts

@@ -0,0 +1,8 @@
+import type { Group } from "../types.js";
+/**
+ * The `skill` group, which documents itself alongside the groups it is given.
+ *
+ * Taking the groups as an argument is what keeps the reference generated rather
+ * than written down twice: a command added anywhere appears here on the next run.
+ */
+export declare function skillCommands(groups: Group[]): Group;

package/dist/commands/skills.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { UsageError } from "../errors.js";
+import { catalogue, document } from "../skills.js";
+const DEFAULT_DIR = ".claude/skills";
+function named(skills, name) {
+    const found = skills.find((skill) => skill.name === name);
+    if (!found) {
+        throw new UsageError(`No skill "${name}". Try: ${skills.map((s) => s.name).join(", ")}.`);
+    }
+    return found;
+}
+function write(ctx, skills) {
+    const dir = ctx.flag("dir") ?? DEFAULT_DIR;
+    const only = ctx.arg(0);
+    const chosen = only ? [named(skills, only)] : skills;
+    const force = ctx.bool("force");
+    return chosen.map((skill) => {
+        const path = join(dir, skill.name, "SKILL.md");
+        if (existsSync(path) && !force)
+            return { skill: skill.name, path, wrote: false };
+        mkdirSync(join(dir, skill.name), { recursive: true });
+        writeFileSync(path, document(skill), "utf8");
+        return { skill: skill.name, path, wrote: true };
+    });
+}
+/**
+ * The `skill` group, which documents itself alongside the groups it is given.
+ *
+ * Taking the groups as an argument is what keeps the reference generated rather
+ * than written down twice: a command added anywhere appears here on the next run.
+ */
+export function skillCommands(groups) {
+    const self = {
+        name: "skill",
+        summary: "agent skills describing this CLI, generated from its own commands",
+        commands: [],
+    };
+    const skills = () => catalogue([...groups, self]);
+    self.commands = [
+        {
+            name: "list",
+            summary: "the skills this CLI can hand an agent",
+            local: true,
+            run: async (ctx) => ({
+                skills: skills().map((skill) => ({
+                    name: skill.name,
+                    description: ctx.bool("full") ? skill.description : `${skill.description.slice(0, 80)}…`,
+                })),
+            }),
+        },
+        {
+            name: "show",
+            summary: "one skill as SKILL.md, on stdout",
+            usage: "<name>",
+            local: true,
+            run: async (ctx) => document(named(skills(), ctx.need(0, "name"))),
+        },
+        {
+            name: "install",
+            summary: "write the skills to --dir (default .claude/skills); --force overwrites",
+            usage: "[name]",
+            local: true,
+            run: async (ctx) => ({ installed: write(ctx, skills()) }),
+        },
+    ];
+    return self;
+}

package/dist/commands/tools.d.ts

@@ -0,0 +1,3 @@
+import type { Group } from "../types.js";
+/** Tools the model can be offered: declaring them, describing them, retiring them. */
+export declare const tools: Group;

package/dist/commands/tools.js

@@ -0,0 +1,70 @@
+import { scoped } from "../context.js";
+import { UsageError } from "../errors.js";
+const EFFECTS = new Set(["readonly", "idempotent", "destructive"]);
+function effect(ctx) {
+    const raw = ctx.flag("effect");
+    if (raw === undefined)
+        return undefined;
+    if (!EFFECTS.has(raw)) {
+        throw new UsageError(`--effect must be one of ${[...EFFECTS].join(", ")}.`);
+    }
+    return raw;
+}
+function args(ctx) {
+    const raw = ctx.list("arg");
+    if (raw === undefined)
+        return undefined;
+    return raw.map((one) => {
+        const [name, type, required] = one.split(":");
+        if (!name || !type)
+            throw new UsageError(`--arg wants name:type, saw "${one}".`);
+        return { name, type, required: required === "required" };
+    });
+}
+const saved = (ctx) => scoped(ctx, ctx.body({
+    name: ctx.flag("name"),
+    description: ctx.flag("description"),
+    args: args(ctx),
+    effect: effect(ctx),
+    pinned: ctx.bool("pinned") || undefined,
+}));
+/** Tools the model can be offered: declaring them, describing them, retiring them. */
+export const tools = {
+    name: "tool",
+    summary: "tools the model can be offered",
+    commands: [
+        {
+            name: "list",
+            summary: "every tool in the project",
+            run: (ctx) => ctx.sg.tools.list({
+                ...ctx.scope(),
+                limit: ctx.num("limit"),
+                cursor: ctx.flag("cursor"),
+                archived: ctx.flag("archived"),
+            }),
+        },
+        {
+            name: "get",
+            summary: "one tool, by uuid or by the name the model calls",
+            usage: "<name>",
+            run: (ctx) => ctx.sg.tools.get(ctx.need(0, "name"), ctx.scope()),
+        },
+        {
+            name: "create",
+            summary: "declare a new tool",
+            run: (ctx) => ctx.sg.tools.create(saved(ctx)),
+        },
+        {
+            name: "update",
+            summary: "rewrite a tool's description, args or effect",
+            usage: "<id>",
+            run: (ctx) => ctx.sg.tools.update(ctx.need(0, "id"), saved(ctx), ctx.scope()),
+        },
+        {
+            name: "archive",
+            summary: "take a tool out of the list; --no-archived brings it back",
+            usage: "<id>",
+            run: (ctx) => ctx.sg.tools.archive(ctx.need(0, "id"), ctx.parsed.flags.archived !== false, ctx.scope()),
+        },
+    ],
+};

package/dist/connect.d.ts

@@ -0,0 +1,19 @@
+import { Spendgraph } from "@spendgraph/sdk";
+import type { Parsed } from "./args.js";
+import type { Env } from "./env.js";
+/** What the CLI proves itself with, and where it points. */
+export interface Credentials {
+    baseUrl: string;
+    apiKey?: string;
+    session?: string;
+    project?: string;
+}
+/**
+ * Reads the credentials from flags first, the environment second.
+ *
+ * Both an `sg_` key and a dashboard session may be set. Which half of the API
+ * each one opens is the server's decision, not this file's.
+ */
+export declare function credentials(parsed: Parsed, env?: Env): Credentials;
+/** The client every command runs against. `fetch` is injected by tests. */
+export declare function connect(creds: Credentials, fetchImpl?: typeof fetch): Spendgraph;

package/dist/connect.js

@@ -0,0 +1,38 @@
+import { Spendgraph } from "@spendgraph/sdk";
+import { UsageError } from "./errors.js";
+const pick = (parsed, name) => {
+    const value = parsed.flags[name];
+    return typeof value === "string" ? value : undefined;
+};
+/**
+ * Reads the credentials from flags first, the environment second.
+ *
+ * Both an `sg_` key and a dashboard session may be set. Which half of the API
+ * each one opens is the server's decision, not this file's.
+ */
+export function credentials(parsed, env = process.env) {
+    const baseUrl = pick(parsed, "base-url") ?? env.SPENDGRAPH_BASE_URL;
+    if (!baseUrl)
+        throw new UsageError("Set --base-url or SPENDGRAPH_BASE_URL.");
+    const apiKey = pick(parsed, "api-key") ?? env.SPENDGRAPH_API_KEY;
+    const session = pick(parsed, "session") ?? env.SPENDGRAPH_SESSION;
+    if (!apiKey && !session) {
+        throw new UsageError("Set SPENDGRAPH_API_KEY, or SPENDGRAPH_SESSION for keys, projects, pricing and credentials.");
+    }
+    return {
+        baseUrl,
+        apiKey,
+        session,
+        project: pick(parsed, "project") ?? env.SPENDGRAPH_PROJECT,
+    };
+}
+/** The client every command runs against. `fetch` is injected by tests. */
+export function connect(creds, fetchImpl) {
+    return new Spendgraph({
+        baseUrl: creds.baseUrl,
+        apiKey: creds.apiKey,
+        session: creds.session,
+        project: creds.project,
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    });
+}

package/dist/context.d.ts

@@ -0,0 +1,13 @@
+import type { Spendgraph } from "@spendgraph/sdk";
+import type { Parsed } from "./args.js";
+import type { Loaded } from "./env.js";
+import type { Ctx } from "./types.js";
+/** Builds the `Ctx` a command runs against. `sg` is null for a command that stays local. */
+export declare function context(sg: Spendgraph | null, parsed: Parsed, positional: string[], loaded: Loaded): Ctx;
+/**
+ * A save body with its `projectId` settled.
+ *
+ * `--file` carrying one is enough on its own, so a definition checked into a
+ * repo applies without the project being named twice.
+ */
+export declare function scoped(ctx: Ctx, body: Record<string, unknown>): Record<string, unknown>;