The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(cli): add 'paperclipai channels' to show release lanes and the current one (#11210)
Devin Foley1ea2f0e2d6fa
diff --git a/cli/src/__tests__/channels.test.ts b/cli/src/__tests__/channels.test.tsnew file mode 100644index 0000000000..97c0ad6222--- /dev/null+++ b/cli/src/__tests__/channels.test.ts@@ -0,0 +1,81 @@+import { describe, expect, it } from "vitest";+import {+ channelForVersion,+ collectChannelState,+ RELEASE_CHANNELS,+} from "../commands/channels.js";+import type { CommandRunner } from "../commands/install.js";++describe("channelForVersion", () => {+ it("maps published versions to their lane", () => {+ expect(channelForVersion("2026.811.0")).toBe("stable");+ expect(channelForVersion("2026.811.0-beta.0")).toBe("beta");+ expect(channelForVersion("2026.811.0-nightly.0")).toBe("nightly");+ expect(channelForVersion("2026.811.0-canary.3")).toBe("canary");+ });++ it("treats non-CalVer versions as unknown instead of guessing", () => {+ expect(channelForVersion("0.3.1")).toBe("unknown");+ expect(channelForVersion("2026.811.0-rc.1")).toBe("unknown");+ expect(channelForVersion("garbage")).toBe("unknown");+ });+});++describe("collectChannelState", () => {+ const versionsByTag: Record<string, string> = {+ latest: "2026.722.0",+ beta: "2026.811.0-beta.0",+ nightly: "2026.811.0-nightly.0",+ canary: "2026.811.0-canary.3",+ };++ const fakeRunner: CommandRunner = async (_command, args) => {+ const spec = (args ?? []).find((arg) => arg.startsWith("paperclipai@"));+ const tag = spec?.slice("paperclipai@".length) ?? "";+ const version = versionsByTag[tag];+ if (!version) throw new Error(`unexpected dist-tag: ${tag}`);+ return { stdout: JSON.stringify(version), stderr: "" };+ };++ it("resolves every channel's dist-tag from the registry", async () => {+ const state = await collectChannelState(fakeRunner);++ expect(state.map((entry) => entry.channel)).toEqual([+ "stable",+ "beta",+ "nightly",+ "canary",+ ]);+ expect(state.map((entry) => entry.version)).toEqual([+ "2026.722.0",+ "2026.811.0-beta.0",+ "2026.811.0-nightly.0",+ "2026.811.0-canary.3",+ ]);+ });++ it("degrades a single unavailable channel to null without failing the rest", async () => {+ const flakyRunner: CommandRunner = async (command, args, options) => {+ const spec = (args ?? []).find((arg) => arg.startsWith("paperclipai@"));+ if (spec === "paperclipai@nightly") throw new Error("registry timeout");+ return fakeRunner(command, args, options);+ };++ const state = await collectChannelState(flakyRunner);+ const byChannel = Object.fromEntries(state.map((entry) => [entry.channel, entry.version]));++ expect(byChannel.nightly).toBeNull();+ expect(byChannel.stable).toBe("2026.722.0");+ expect(byChannel.beta).toBe("2026.811.0-beta.0");+ expect(byChannel.canary).toBe("2026.811.0-canary.3");+ });++ it("keeps the channel table and dist-tags in sync", () => {+ expect(RELEASE_CHANNELS.map((entry) => entry.distTag)).toEqual([+ "latest",+ "beta",+ "nightly",+ "canary",+ ]);+ });+});diff --git a/cli/src/commands/channels.ts b/cli/src/commands/channels.tsnew file mode 100644index 0000000000..3fe211b495--- /dev/null+++ b/cli/src/commands/channels.ts@@ -0,0 +1,119 @@+import { execFile } from "node:child_process";+import { promisify } from "node:util";+import pc from "picocolors";+import { resolvePublishedVersion, type CommandRunner } from "./install.js";+import { packageVersion } from "../version.js";++const execFileAsync = promisify(execFile);++const defaultRunCommand: CommandRunner = (command, args, options) =>+ execFileAsync(command, args, { ...options, encoding: "utf8" });++export type ChannelName = "stable" | "beta" | "nightly" | "canary";++export type ChannelDescriptor = {+ channel: ChannelName;+ distTag: string;+ cadence: string;+ audience: string;+};++// Ordered from most to least stable — the order users should consider them.+export const RELEASE_CHANNELS: readonly ChannelDescriptor[] = [+ {+ channel: "stable",+ distTag: "latest",+ cadence: "manual, soaked in beta for 3+ days",+ audience: "the recommended release for almost everyone",+ },+ {+ channel: "beta",+ distTag: "beta",+ cadence: "manual promotion behind an approval gate",+ audience: "release candidates: what stable becomes a few days later",+ },+ {+ channel: "nightly",+ distTag: "nightly",+ cadence: "once a night, smoke-gated",+ audience: "yesterday's merges, tested as a unit",+ },+ {+ channel: "canary",+ distTag: "canary",+ cadence: "every merge to master",+ audience: "the bleeding edge",+ },+];++const CALVER_RE = /^\d{4}\.\d{1,4}\.\d+$/;+const PRERELEASE_RE = /^\d{4}\.\d{1,4}\.\d+-(canary|nightly|beta)\.\d+$/;++// Published versions carry their lane in the version string; the source+// checkout's package.json holds a placeholder that matches neither form.+export function channelForVersion(version: string): ChannelName | "unknown" {+ const prerelease = version.match(PRERELEASE_RE);+ if (prerelease) return prerelease[1] as ChannelName;+ if (CALVER_RE.test(version)) return "stable";+ return "unknown";+}++export type ChannelState = ChannelDescriptor & { version: string | null };++export async function collectChannelState(+ runCommand: CommandRunner = defaultRunCommand,+): Promise<ChannelState[]> {+ const resolved = await Promise.allSettled(+ RELEASE_CHANNELS.map((entry) => resolvePublishedVersion(entry.distTag, runCommand)),+ );+ return RELEASE_CHANNELS.map((entry, index) => {+ const outcome = resolved[index];+ return {+ ...entry,+ version: outcome.status === "fulfilled" ? outcome.value : null,+ };+ });+}++export type ChannelsOptions = { json?: boolean };++export async function channelsCommand(+ options: ChannelsOptions = {},+ runCommand: CommandRunner = defaultRunCommand,+): Promise<void> {+ const state = await collectChannelState(runCommand);+ const currentChannel = channelForVersion(packageVersion);++ if (options.json) {+ console.log(+ JSON.stringify(+ {+ current: { version: packageVersion, channel: currentChannel },+ channels: state,+ },+ null,+ 2,+ ),+ );+ return;+ }++ console.log(pc.bold("Paperclip release channels"));+ console.log("");+ for (const entry of state) {+ const version = entry.version ?? pc.yellow("unavailable");+ console.log(` ${pc.bold(entry.channel.padEnd(8))} ${version}`);+ console.log(` ${" ".repeat(8)} ${pc.dim(`${entry.cadence} — ${entry.audience}`)}`);+ console.log(` ${" ".repeat(8)} ${pc.dim(`npx paperclipai@${entry.distTag} onboard`)}`);+ console.log("");+ }++ if (currentChannel === "unknown") {+ console.log(+ `This install reports version ${pc.bold(packageVersion)}, which does not map to a published channel (source checkouts report the repository placeholder).`,+ );+ } else {+ console.log(`This install is version ${pc.bold(packageVersion)} on the ${pc.bold(currentChannel)} channel.`);+ }+ console.log(`Docker images use the same names: ghcr.io/paperclipai/paperclip:{latest,beta,nightly,canary}`);+}diff --git a/cli/src/index.ts b/cli/src/index.tsindex fd8d1ee4f7..b26b5cbe18 100644--- a/cli/src/index.ts+++ b/cli/src/index.ts@@ -2,6 +2,7 @@ import { Command } from "commander";import { onboard } from "./commands/onboard.js";import { doctor } from "./commands/doctor.js";import { envCommand } from "./commands/env.js";+import { channelsCommand } from "./commands/channels.js";import { configure } from "./commands/configure.js";import { addAllowedHostname } from "./commands/allowed-hostname.js";import { heartbeatRun } from "./commands/heartbeat-run.js";@@ -130,6 +131,14 @@ program.option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP).action(envCommand);+program+ .command("channels")+ .description("Show the release channels and which one this install follows")+ .option("--json", "Machine-readable output")+ .action(async (opts) => {+ await channelsCommand(opts);+ });+program.command("configure").description("Update configuration sections")diff --git a/doc/CHANNELS.md b/doc/CHANNELS.mdindex b99ae33a3d..f809a386fc 100644--- a/doc/CHANNELS.md+++ b/doc/CHANNELS.md@@ -56,6 +56,16 @@ docker pull ghcr.io/paperclipai/paperclip:canaryEvery image is also published as `:sha-<short-sha>` for exact pinning, andstable images additionally get `:YYYY.MDD.P` version tags.+## Seeing where you are++```bash+npx paperclipai channels+```++prints every channel with the version it currently resolves to, the install+command for each, and which channel your install follows (with `--json` for+scripting).+## Switching channelsChannel choice is per-install: install from a different tag and you're on that