@labelbox/recursion-cli 0.0.45 → 0.0.47

package/README.md

@@ -1,44 +1,63 @@
 # @labelbox/recursion-cli
 
-`rl` — the Recursion CLI. It mirrors the TypeScript SDK
+`recursion` — the Recursion CLI. It mirrors the TypeScript SDK
 (`@labelbox/recursion-sdk`) exactly: where the SDK is `rl.synthesizers.create(...)`, the
-CLI is `rl synthesizers create …`. Dots become spaces; you get `--help` at every
-level.
+CLI is `recursion synthesizers create …`. Dots become spaces; you get `--help` at every
+level. The existing `rl` executable remains a temporary compatibility alias and
+runs the same command tree; new usage should prefer `recursion`.
 
 ```sh
-rl --help                     # list nouns (synthesizers, synthesizer-runs)
-rl synthesizers --help        # list verbs (create, get, list, …)
-rl synthesizers create --help # list flags
+recursion --help                     # list nouns (synthesizers, synthesizer-runs)
+recursion synthesizers --help        # list verbs (create, get, list, …)
+recursion synthesizers create --help # list flags
 ```
 
 ## How it works (fully live, zero per-operation code)
 
 The CLI ships **no** baked API reference and has **no** `@labelbox/recursion-sdk` dependency.
-On each run it **fetches a manifest** from `GET /cli/manifest` on whatever server
-`--base-url` points at (production by default, or staging, or `localhost`), validates
-it (`src/manifest.ts`), and builds its entire command tree, `--help`, request/response
-shapes, and docs browse surfaces from it. Dispatch is generic (`src/dispatch.ts`):
+On each run it **revalidates the manifest** from `GET /cli/manifest` when the server
+selected by `--base-url` is reachable (production by default, or staging, or
+`localhost`). If the server is unavailable, it falls back only to a locally cached
+manifest that was previously validated. From that manifest it builds its entire
+command tree, `--help`, request/response shapes, and docs browse surfaces
+(`src/manifest.ts`). Dispatch is generic (`src/dispatch.ts`):
 each request is built straight from the manifest operation's HTTP method + path
 template + params + body — there is no hand-written command per operation and no
 baked client.
 
 The result: **adding or changing a backend endpoint needs zero CLI release** — the
 live CLI reflects it as soon as the backend deploys. The CLI is re-released only when
-its own engine code changes. The manifest is revalidated on every run via a
-conditional fetch (ETag / `If-None-Match`), cached per base-url under
-`~/.cache/rl-gym/`, so it can never serve stale data and never needs manual busting.
+its own engine code changes. When the server is reachable, the manifest is
+revalidated on every run via a conditional fetch (ETag / `If-None-Match`) and cached
+per base-url under `~/.cache/recursion/`. When the server is unreachable, the CLI may
+use the last locally validated copy so commands remain available offline. If only the
+previous `~/.cache/rl-gym/` entry exists, the CLI validates and uses it immediately,
+then adopts it into the Recursion cache non-destructively. The
+old entry is retained unchanged for rollback; new server responses are written only
+to the Recursion cache.
+
+Legacy adoption uses atomic create-if-absent publication: a validated copy is
+hard-linked from a unique same-directory temporary file, so it never replaces a
+canonical entry created concurrently. A valid concurrent canonical entry wins; an
+invalid one is left untouched while that invocation uses the validated legacy value
+in memory. Validated fresh HTTP `200` responses use atomic same-directory rename and
+therefore retain last-network-writer behavior. Replacement preserves an existing
+file's POSIX mode bits, but deliberately publishes a new inode and does not preserve
+its ACLs or extended attributes. Both paths require parent-directory write/search
+permission; if unavailable, the CLI keeps using the validated in-memory result and
+never falls back to a partial direct write.
 
 ### Docs browse surfaces
 
-Beyond the executable `rl <noun> <verb>` operations, the manifest carries the docs,
-exposed as one consistent positional shape — `rl <group> [<id>]` (bare lists, an id
+Beyond the executable `recursion <noun> <verb>` operations, the manifest carries the docs,
+exposed as one consistent positional shape — `recursion <group> [<id>]` (bare lists, an id
 shows that one):
 
 ```sh
-rl resources [<id>]    # Reference — resource hubs: object shape, operations, recipes
-rl recipes  [<id>]     # How-to — multi-step user-goal guides (--format cli|ts|curl)
-rl explain  [<concept>] # Explanation — concept pages
-rl tutorials [<id>]    # Tutorials — getting-started docs
+recursion resources [<id>]    # Reference — resource hubs: object shape, operations, recipes
+recursion recipes  [<id>]     # How-to — multi-step user-goal guides (--format cli|ts|curl)
+recursion explain  [<concept>] # Explanation — concept pages
+recursion tutorials [<id>]    # Tutorials — getting-started docs
 ```
 
 ## Install / run
@@ -48,9 +67,9 @@ setup beyond Node itself.
 
 ```sh
 npm uninstall -g @recursion/cli @labelbox/rl-cli   # no-op unless a pre-rename package is installed
-npm install -g @labelbox/recursion-cli   # they all own the global `rl` bin — EEXIST otherwise
+npm install -g @labelbox/recursion-cli   # old packages also own the `rl` alias — EEXIST otherwise
 # or, zero-install:
-npx @labelbox/recursion-cli --help
+npx --package @labelbox/recursion-cli recursion --help
 ```
 
 The CLI is standalone, so this pulls in no `@labelbox/recursion-sdk`.
@@ -92,19 +111,21 @@ host with `--base-url <url>` (defaults to the public Recursion API gateway, see
   no-content operations).
 
 ```sh
-rl synthesizers get --synthesizer-job-id sj_01HX...
-rl synthesizers create --environment-id env_01HX... --from-json ./body.json
-rl synthesizer-runs trigger --problem-version-id pv_01HX... --from-json ./run.json
+recursion synthesizers get --synthesizer-job-id sj_01HX...
+recursion synthesizers create --environment-id env_01HX... --from-json ./body.json
+recursion synthesizer-runs trigger --problem-version-id pv_01HX... --from-json ./run.json
 ```
 
 ## The command surface is the live server
 
 There is **nothing to regenerate or commit** for the CLI — the command surface is
-fetched fresh from the target server's `GET /cli/manifest` on every run, so a backend
-change flows through automatically after deploy with no CLI step. The manifest itself
-is assembled by `yarn generate cli:manifest` (included in `yarn generate prerequisites`) from the
-spec-derived reference files and embedded into the backend; to add or change a
-command, change the backend `@SdkRoute` — not this package.
+revalidated against the target server's `GET /cli/manifest` on every run when the
+server is reachable, with a validated local-cache fallback when it is offline. A
+backend change therefore flows through automatically after deploy with no CLI step.
+The manifest itself is assembled by `yarn generate cli:manifest` (included in
+`yarn generate prerequisites`) from the spec-derived reference files and embedded
+into the backend; to add or change a command, change the backend `@SdkRoute` — not
+this package.
 
 The *engine* (manifest fetch + cache + validation, generic dispatch, flag mapping,
 help formatting, the request-body / returns shape trees, and the docs browse

package/dist/embed.d.ts

@@ -8,7 +8,7 @@ export interface ExecuteCliOptions {
     apiKey: string;
     /** The API the CLI dispatches against. Server configuration, not caller input. */
     baseUrl: string;
-    /** Reported by `rl --version`. */
+    /** Reported by `recursion --version`. */
     version: string;
     /** The pre-assembled manifest — served from memory, never re-fetched over HTTP. */
     manifest: Manifest;
@@ -31,7 +31,7 @@ export interface CliResult {
  */
 export declare function assertAllowedArgv(args: readonly string[]): void;
 /**
- * Run one `rl` invocation in-process and capture its output.
+ * Run one `recursion` invocation in-process and capture its output.
  *
  * Resolves for both success and failure — a non-zero exit is a normal outcome the
  * model should see and correct from, not an exception. It rejects only on a

package/dist/embed.js

@@ -1,5 +1,5 @@
 import { run } from './run.js';
-// Running `rl` inside a server process, on behalf of an agent, without a shell.
+// Running `recursion` inside a server process, on behalf of an agent, without a shell.
 //
 // The MCP endpoint exposes one tool whose argument is an argv array. This module
 // is the whole surface it needs: `executeCli` builds the argv, runs the same
@@ -91,11 +91,11 @@ export function assertAllowedArgv(args) {
     const command = args.find((arg) => !arg.startsWith('-'));
     if (command !== undefined && BLOCKED_COMMANDS.has(command)) {
         throw new Error(`"${command}" is not available here: it acts on a local developer checkout, ` +
-            'which this server does not have. Run it from your own terminal with the rl CLI.');
+            'which this server does not have. Run it from your own terminal with the recursion CLI.');
     }
 }
 /**
- * Run one `rl` invocation in-process and capture its output.
+ * Run one `recursion` invocation in-process and capture its output.
  *
  * Resolves for both success and failure — a non-zero exit is a normal outcome the
  * model should see and correct from, not an exception. It rejects only on a
@@ -125,7 +125,7 @@ export async function executeCli(options) {
         // argv can outrank it.
         argv: [
             'node',
-            'rl',
+            'recursion',
             `--api-key=${options.apiKey}`,
             `--base-url=${options.baseUrl}`,
             ...options.args,

package/dist/git-host.js

@@ -128,7 +128,7 @@ function stashClaim(repoDir, claim) {
 function readStashedClaim(repoDir) {
     const path = claimFilePath(repoDir);
     if (!existsSync(path)) {
-        throw new Error(`no claim found at ${path} — run \`rl scaffold\` in this directory first, or pass --path to point at a scaffolded repo`);
+        throw new Error(`no claim found at ${path} — run \`recursion scaffold\` in this directory first, or pass --path to point at a scaffolded repo`);
     }
     const parsed = StashedClaimSchema.safeParse(JSON.parse(readFileSync(path, 'utf8')));
     if (!parsed.success) {

package/dist/manifest.d.ts

@@ -398,13 +398,22 @@ export type Manifest = z.infer<typeof ManifestSchema>;
  * and only a deliberate format bump trips this.
  */
 export declare function parseManifest(value: unknown, source: string): Manifest;
+/**
+ * A filesystem-safe, collision-free slug for a base URL, so each server caches
+ * independently. The readable part is the sanitized URL (handy when eyeballing the
+ * cache dir); a short hash of the *full* URL is appended so two URLs that sanitize
+ * to the same string (e.g. `https://x.com:8080` vs `https://x-com-8080`) still get
+ * distinct cache files rather than silently sharing — and poisoning — one.
+ */
+export declare function hostSlug(baseUrl: string): string;
 /**
  * Fetch the command manifest, revalidating the cache on every run:
  *   - send `If-None-Match` with the cached ETag → `304` means the cache is provably
  *     current (use it); `200` means the surface changed (validate + replace cache).
  *   - a network error (incl. a timeout) falls back to the cached copy with a warning;
  *     with no cache it errors clearly.
- * The cache therefore can never serve stale data and never needs manual busting — a
- * backend redeploy is picked up automatically on the next command.
+ * When the server is reachable, the cache is revalidated and a backend redeploy is
+ * picked up automatically. Offline, the last locally validated copy may be older
+ * than the server but keeps the CLI usable.
  */
 export declare function fetchManifest(baseUrl: string, apiKey: string): Promise<Manifest>;

package/dist/manifest.js

@@ -1,5 +1,5 @@
-import { createHash } from 'node:crypto';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, fchmodSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import process from 'node:process';
@@ -9,8 +9,8 @@ import { z } from 'zod';
 // from `GET /cli/manifest` on whatever server `--base-url` points at, instead of
 // baking a compiled-in `@labelbox/recursion-sdk` reference. This module owns:
 //   1. the manifest's runtime Zod schema + TS types (the validation boundary), and
-//   2. `fetchManifest` — a conditional-fetch cache (ETag / If-None-Match) that can
-//      never serve stale data and needs no manual busting.
+//   2. `fetchManifest` — a conditional-fetch cache (ETag / If-None-Match) that is
+//      revalidated whenever the server is reachable and remains usable offline.
 // The schema lives here, not in sdk-ts: the CLI no longer depends on that package
 // (see the plan's standalone-CLI decision). The backend embeds the same manifest at
 // build time (`dx manifest:generate`); this is the consumer mirror.
@@ -159,7 +159,7 @@ export const ManifestOperationSchema = z.object({
     params: z.array(ManifestParamSchema),
     response: ShapeNodeSchema.optional(),
 });
-// ── Resources — the Reference browse surface (`rl resources [<id>]`) ──────────
+// ── Resources — the Reference browse surface (`recursion resources [<id>]`) ──────────
 const ManifestResourceObjectSchema = z.object({
     name: z.string(),
     fields: z.array(ShapeNodeSchema),
@@ -175,14 +175,14 @@ export const ManifestResourceSchema = z.object({
     object: ManifestResourceObjectSchema.optional(),
     operationIds: z.array(z.string()),
 });
-// ── Recipes — the How-to browse surface (`rl recipes [<id>]`) ─────────────────
+// ── Recipes — the How-to browse surface (`recursion recipes [<id>]`) ─────────────────
 const RecipeSnippetSchema = z.object({ setup: z.string(), main: z.string() });
 // Steps are read only to map a recipe to the resources it touches (via each SDK
 // step's operationId), so they're modeled loosely — just the fields the CLI uses.
 const ManifestRecipeStepSchema = z.object({ operationId: z.string().optional() });
 // A recipe's place in the relationship graph (mirrors `RecipeRelated` in
 // sdk-ts's recipes-schema). Modeled loosely here — the CLI only reads these to
-// render the "Related" / "Unblocks" block on `rl recipes <id>`; the generator
+// render the "Related" / "Unblocks" block on `recursion recipes <id>`; the generator
 // is the source of truth that validates them. Without these fields the manifest
 // parse would silently strip `related`, so the CLI would never see the links.
 const ManifestLinkTargetSchema = z.object({
@@ -224,7 +224,7 @@ export const ManifestRecipeSchema = z.object({
     // The recipe's relationship links (optional — absent for an island recipe).
     related: ManifestRelatedSchema.optional(),
 });
-// ── Concepts — the Explanation browse surface (`rl explain [<concept>]`) ──────
+// ── Concepts — the Explanation browse surface (`recursion explain [<concept>]`) ──────
 export const ManifestConceptSchema = z.object({
     id: z.string(),
     title: z.string(),
@@ -234,7 +234,7 @@ export const ManifestConceptSchema = z.object({
     // metadata — the frontend fetches the `.md` separately; the CLI bundles it).
     body: z.string(),
 });
-// ── Tutorials — the getting-started docs (`rl tutorials [<id>]`) ──────────────
+// ── Tutorials — the getting-started docs (`recursion tutorials [<id>]`) ──────────────
 export const ManifestTutorialSchema = z.object({
     id: z.string(),
     title: z.string(),
@@ -279,7 +279,7 @@ export function parseManifest(value, source) {
                 // means no pre-rename package (@labelbox/rl-cli, or the older
                 // @recursion/cli) owns the `rl` bin. A pre-rename user sees the
                 // pre-rename binary's own message instead.
-                'this `rl` CLI is out of date — upgrade it (`npm install -g @labelbox/recursion-cli`)'
+                'this `recursion` CLI is out of date — upgrade it (`npm install -g @labelbox/recursion-cli`)'
             : 'the server is older than this CLI — point --base-url at an up-to-date server';
         throw new Error(`command-manifest format mismatch: this CLI speaks v${MANIFEST_FORMAT_VERSION}, ` +
             `${source} served v${formatVersion}. ${direction}.`);
@@ -300,12 +300,15 @@ const CacheSchema = z.object({ etag: z.string().optional(), manifest: z.unknown(
  * to the same string (e.g. `https://x.com:8080` vs `https://x-com-8080`) still get
  * distinct cache files rather than silently sharing — and poisoning — one.
  */
-function hostSlug(baseUrl) {
+export function hostSlug(baseUrl) {
     const readable = baseUrl.replace(/[^a-zA-Z0-9]+/gu, '-').replace(/^-+|-+$/gu, '') || 'default';
     const hash = createHash('sha256').update(baseUrl, 'utf8').digest('hex').slice(0, 8);
     return `${readable}-${hash}`;
 }
-function cachePathFor(baseUrl) {
+function canonicalCachePathFor(baseUrl) {
+    return join(homedir(), '.cache', 'recursion', `${hostSlug(baseUrl)}.json`);
+}
+function legacyCachePathFor(baseUrl) {
     return join(homedir(), '.cache', 'rl-gym', `${hostSlug(baseUrl)}.json`);
 }
 function readCache(path) {
@@ -333,23 +336,131 @@ function readCache(path) {
     // arrives). Treating it as cold lets the next fetch pull — and re-cache — a full
     // body, so the CLI self-heals without a manual cache delete.
     try {
-        return { etag: parsed.data.etag, manifest: parseManifest(parsed.data.manifest, 'the cache') };
+        return {
+            etag: parsed.data.etag,
+            manifest: parseManifest(parsed.data.manifest, 'the cache'),
+            raw,
+        };
     }
     catch {
         return undefined;
     }
 }
-function writeCache(path, entry) {
+const CACHE_TEMP_PREFIX = '.rlc-';
+function uniqueCacheTempPath(directory) {
+    return join(directory, `${CACHE_TEMP_PREFIX}${process.pid.toString()}-${randomUUID()}.tmp`);
+}
+/**
+ * Create, populate, close, and publish one exclusively owned same-directory temp.
+ *
+ * Ownership begins immediately after `openSync` succeeds, so every later failure —
+ * including a partial write or close failure — triggers best-effort pathname cleanup.
+ * Descriptor ownership is cleared before the single close attempt: retrying a numeric
+ * descriptor could close an unrelated resource if the operating system reused it.
+ * Publication happens only after close succeeds. The caller reports whether it
+ * transferred the inode (rename) or retained it (hard-link adoption), which determines
+ * final cleanup ownership.
+ */
+function publishFromOwnedTemp(path, raw, prepare, publish) {
+    let tempPath;
+    let descriptor;
+    let ownsTemp = false;
     try {
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, JSON.stringify(entry));
+        const directory = dirname(path);
+        mkdirSync(directory, { recursive: true });
+        tempPath = uniqueCacheTempPath(directory);
+        descriptor = openSync(tempPath, 'wx');
+        ownsTemp = true;
+        const bytes = Buffer.from(raw, 'utf8');
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const written = writeSync(descriptor, bytes, offset, bytes.byteLength - offset);
+            if (written === 0)
+                throw new Error('writing the cache temp made no progress');
+            offset += written;
+        }
+        prepare(descriptor);
+        const descriptorToClose = descriptor;
+        descriptor = undefined;
+        closeSync(descriptorToClose);
+        if (publish(tempPath) === 'transferred')
+            ownsTemp = false;
     }
     catch {
-        // A non-writable cache dir is a bandwidth optimization lost, not a failure —
-        // the command still ran off the fetched manifest. Stay silent.
+        // Cache persistence is a bandwidth optimization. The caller already has a
+        // validated in-memory manifest, so publication failures are non-fatal.
     }
+    finally {
+        if (descriptor !== undefined) {
+            const descriptorToClose = descriptor;
+            descriptor = undefined;
+            try {
+                closeSync(descriptorToClose);
+            }
+            catch {
+                // Never retry a numeric descriptor: it may already have been reused.
+            }
+        }
+        if (ownsTemp && tempPath !== undefined) {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch {
+                // Pathname cleanup is best-effort; readers inspect only the final path.
+            }
+        }
+    }
+}
+/**
+ * Replace a cache with a validated HTTP 200 response via same-directory rename.
+ *
+ * Rename deliberately publishes a new inode: an existing destination's POSIX mode
+ * bits are copied to that inode, but its ACLs and xattrs are not. The operation
+ * requires write/search permission on the parent directory; it never falls back to
+ * a partial direct write when temporary-file creation or rename is unavailable.
+ */
+function replaceCacheAtomically(path, raw) {
+    publishFromOwnedTemp(path, raw, (descriptor) => {
+        // Read the mode immediately before publication. Concurrent HTTP 200 writers all
+        // preserve the established mode while rename keeps last-network-writer-wins.
+        const destination = statSync(path, { throwIfNoEntry: false });
+        if (destination !== undefined)
+            fchmodSync(descriptor, destination.mode & 0o7777);
+    }, (tempPath) => {
+        renameSync(tempPath, path);
+        return 'transferred';
+    });
+}
+/**
+ * Publish validated legacy bytes only if the canonical destination is absent.
+ *
+ * The hard link is the no-replace commit point: unlike rename, it fails if any
+ * concurrent invocation has created the destination. Best-effort temporary-path
+ * cleanup is attempted afterward, while a winning canonical path is never overwritten.
+ */
+function publishCacheIfAbsent(path, raw) {
+    publishFromOwnedTemp(path, raw, () => { }, (tempPath) => {
+        linkSync(tempPath, path);
+        return 'retained';
+    });
+}
+/** Prefer canonical cache; otherwise adopt a validated legacy file without mutating it. */
+function selectCache(baseUrl) {
+    const canonicalPath = canonicalCachePathFor(baseUrl);
+    const canonical = readCache(canonicalPath);
+    if (canonical !== undefined)
+        return canonical;
+    const legacy = readCache(legacyCachePathFor(baseUrl));
+    if (legacy === undefined)
+        return undefined;
+    // Copy the validated bytes exactly. Hard-link publication cannot replace a
+    // canonical file that appears after the reads above. Re-read afterward: prefer a
+    // valid concurrent winner, but leave an invalid winner untouched and keep using
+    // the already-validated legacy value in memory.
+    publishCacheIfAbsent(canonicalPath, legacy.raw);
+    return readCache(canonicalPath) ?? legacy;
 }
-// Every `rl` invocation gates on this fetch, so it must be bounded: a server that
+// Every `recursion` invocation gates on this fetch, so it must be bounded: a server that
 // accepts the connection but never responds (a hung gateway, a stalled captive
 // portal) would otherwise hang the CLI forever. A timeout makes `fetch` reject, so
 // the catch below degrades to the cached manifest (or the clear cold-cache error).
@@ -360,13 +471,14 @@ const MANIFEST_FETCH_TIMEOUT_MS = 30_000;
  *     current (use it); `200` means the surface changed (validate + replace cache).
  *   - a network error (incl. a timeout) falls back to the cached copy with a warning;
  *     with no cache it errors clearly.
- * The cache therefore can never serve stale data and never needs manual busting — a
- * backend redeploy is picked up automatically on the next command.
+ * When the server is reachable, the cache is revalidated and a backend redeploy is
+ * picked up automatically. Offline, the last locally validated copy may be older
+ * than the server but keeps the CLI usable.
  */
 export async function fetchManifest(baseUrl, apiKey) {
     const url = supportUrl(baseUrl, '/cli/manifest');
-    const cachePath = cachePathFor(baseUrl);
-    const cached = readCache(cachePath);
+    const canonicalCachePath = canonicalCachePathFor(baseUrl);
+    const cached = selectCache(baseUrl);
     let res;
     try {
         res = await fetch(url, {
@@ -410,6 +522,6 @@ export async function fetchManifest(baseUrl, apiKey) {
             'points at a recursion API (not a login page or proxy).');
     }
     const manifest = parseManifest(json, url);
-    writeCache(cachePath, { etag: res.headers.get('etag') ?? undefined, manifest: json });
+    replaceCacheAtomically(canonicalCachePath, JSON.stringify({ etag: res.headers.get('etag') ?? undefined, manifest: json }));
     return manifest;
 }

package/dist/program.d.ts

@@ -20,7 +20,7 @@ export declare function parseBodyBase(opts: Record<string, unknown>): Record<str
  * Where CLI output goes, and the reason nothing here touches `process` directly.
  *
  * The terminal entrypoint (`bin.ts`) binds these to the real streams. The MCP
- * endpoint binds them to string buffers so one `rl` invocation can be executed
+ * endpoint binds them to string buffers so one `recursion` invocation can be executed
  * **in-process** on behalf of an agent and its output returned as a tool result.
  * A stray `process.stdout.write` would leak an agent's output into the server's
  * logs; a stray `process.exit` would take the whole API server down mid-request.
@@ -86,7 +86,7 @@ export declare function leafShapeHelp(entry: ManifestOperation): string;
  * and `--data` is the single documented way to pass a body.
  */
 export declare function addOptions(command: Command, entry: ManifestOperation, fileFlags?: boolean): void;
-/** Output formats `rl recipes <id>` can render, mapped to the composed snippet field. */
+/** Output formats `recursion recipes <id>` can render, mapped to the composed snippet field. */
 declare const RECIPE_FORMATS: {
     readonly cli: "cli";
     readonly ts: "sdk";
@@ -94,7 +94,7 @@ declare const RECIPE_FORMATS: {
     readonly curl: "curl";
 };
 export type RecipeFormat = keyof typeof RECIPE_FORMATS;
-/** The full catalog, grouped by category, for `rl recipes`. */
+/** The full catalog, grouped by category, for `recursion recipes`. */
 export declare function renderRecipeList(reference: Record<string, ManifestRecipe>): string;
 /**
  * The "Related" + "Unblocks" block for a recipe — its place in the graph. The
@@ -104,10 +104,10 @@ export declare function renderRecipeList(reference: Record<string, ManifestRecip
  * and where it can go next. Returns `''` when the recipe is an island.
  */
 export declare function renderRelatedBlock(entry: ManifestRecipe, allRecipes: Record<string, ManifestRecipe>): string;
-/** One recipe rendered for `rl recipes <id>`: goal + composed code + related links + a docs link. */
+/** One recipe rendered for `recursion recipes <id>`: goal + composed code + related links + a docs link. */
 export declare function renderRecipeShow(entry: ManifestRecipe, format: RecipeFormat, allRecipes: Record<string, ManifestRecipe>): string;
 /** The program shell — name, description, version, and the global options. */
 export declare function buildBaseProgram(version: string, io: CliIo): Command;
-/** Build the full `rl` program from a fetched manifest. */
+/** Build the full `recursion` program from a fetched manifest. */
 export declare function buildProgram(manifest: Manifest, ctx: ProgramContext): Command;
 export {};

package/dist/program.js

@@ -336,7 +336,7 @@ export function addOptions(command, entry, fileFlags = true) {
     // resource type as their request body, so `agent_id` is both the path
     // parameter and a property of the body schema. Commander throws when the same
     // flag is added twice, and that throw happens while the whole program is
-    // being built, so one such operation takes down `rl` entirely rather than
+    // being built, so one such operation takes down `recursion` entirely rather than
     // just itself. Path and query win: they address the resource and are what the
     // URL is built from. The shadowed body field is still settable through
     // `--from-json` / `--data`.
@@ -386,15 +386,15 @@ export function addOptions(command, entry, fileFlags = true) {
         command.option('--data <json>', 'Inline JSON request body');
     }
 }
-// ── docs browse surfaces — one consistent shape: `rl <group> [<id>]` ─────────
+// ── docs browse surfaces — one consistent shape: `recursion <group> [<id>]` ─────────
 //
 // All four read-only browse groups (resources / recipes / explain / tutorials)
 // take one positional shape: bare lists, an id shows that one. No `show`/`list`
-// verbs (those are the action layer's, `rl <noun> <verb>`). All data is the live
+// verbs (those are the action layer's, `recursion <noun> <verb>`). All data is the live
 // manifest; these commands are pure presentation (no further network).
 // The Labelbox app host (not the recursion API base) — recipes/docs render in-app.
 const RECIPE_DOCS_BASE_URL = 'https://app.labelbox.com';
-/** Output formats `rl recipes <id>` can render, mapped to the composed snippet field. */
+/** Output formats `recursion recipes <id>` can render, mapped to the composed snippet field. */
 const RECIPE_FORMATS = { cli: 'cli', ts: 'sdk', py: 'python', curl: 'curl' };
 function isRecipeFormat(value) {
     return Object.hasOwn(RECIPE_FORMATS, value);
@@ -421,7 +421,7 @@ function groupByDomain(entries, domainOf, domains) {
 const ACTIONS_HELP_GROUP = 'Actions:';
 const DOCS_HELP_GROUP = 'Documentation:';
 const GIT_HOST_HELP_GROUP = 'Coding tasks:';
-/** Nested resource groups (`rl problems --help`, etc.) — allowed subcommands. */
+/** Nested resource groups (`recursion problems --help`, etc.) — allowed subcommands. */
 const COMMANDS_HELP_GROUP = 'Commands';
 /** Nested resource groups — subcommands the caller can't run (separate help section). */
 const UNAVAILABLE_HELP_GROUP = 'Unavailable (missing permission)';
@@ -463,7 +463,7 @@ function resolveResourceDomain(resource, byId) {
     }
     return undefined;
 }
-/** The `rl <callPath>` invocation for an operation, with its required-flag hints. */
+/** The `recursion <callPath>` invocation for an operation, with its required-flag hints. */
 function operationInvocation(op) {
     const flags = [];
     for (const param of op.params) {
@@ -475,12 +475,12 @@ function operationInvocation(op) {
     if (op.bodyKey)
         flags.push('--data <json>');
     // kebab each segment so the printed command matches the real one (the tree is
-    // built from `kebab(segment)`) — `rl environments attach-external-id`, not the
+    // built from `kebab(segment)`) — `recursion environments attach-external-id`, not the
     // camelCase callPath.
     const command = op.callPath.map(kebab).join(' ');
-    return `rl ${command}${flags.length ? ` ${flags.join(' ')}` : ''}`;
+    return `recursion ${command}${flags.length ? ` ${flags.join(' ')}` : ''}`;
 }
-/** `rl resources [<id>]` — the Reference hub (grouped browse, or one resource). */
+/** `recursion resources [<id>]` — the Reference hub (grouped browse, or one resource). */
 function addResourcesCommand(program, manifest, io) {
     const byId = manifest.resources;
     program
@@ -493,11 +493,11 @@ function addResourcesCommand(program, manifest, io) {
             return;
         }
         // `Object.hasOwn`, not `byId[id]`: a Zod `z.record` is a plain object, so a bare
-        // read walks the prototype chain — `rl resources constructor` would resolve to a
+        // read walks the prototype chain — `recursion resources constructor` would resolve to a
         // truthy inherited member, bypass the not-found guard, and crash in the renderer.
         const entry = Object.hasOwn(byId, id) ? byId[id] : undefined;
         if (!entry) {
-            throw new Error(`unknown resource "${id}". Run \`rl resources\` to list resources.`);
+            throw new Error(`unknown resource "${id}". Run \`recursion resources\` to list resources.`);
         }
         io.stdout(renderResourceShow(entry, manifest));
     });
@@ -506,7 +506,7 @@ function renderResourceList(manifest) {
     const byId = manifest.resources;
     const all = Object.values(byId);
     const groups = groupByDomain(all, (r) => resolveResourceDomain(r, byId), manifest.domains);
-    const lines = ['Resources — run `rl resources <id>` for the full overview.', ''];
+    const lines = ['Resources — run `recursion resources <id>` for the full overview.', ''];
     for (const group of groups) {
         lines.push(group.title);
         const sorted = group.entries.sort((a, b) => a.order - b.order || a.id.localeCompare(b.id, 'en'));
@@ -549,7 +549,7 @@ function renderResourceShow(resource, manifest) {
     }
     return `${parts.join('\n')}\n`;
 }
-/** `rl recipes [<id>]` — How-to (list grouped by category, or one recipe). */
+/** `recursion recipes [<id>]` — How-to (list grouped by category, or one recipe). */
 function addRecipesCommand(program, manifest, io) {
     program
         .command('recipes [id]')
@@ -564,7 +564,7 @@ function addRecipesCommand(program, manifest, io) {
         // Object.hasOwn guards the prototype chain (see the resources hub above).
         const entry = Object.hasOwn(manifest.recipes, id) ? manifest.recipes[id] : undefined;
         if (!entry) {
-            throw new Error(`unknown recipe "${id}". Run \`rl recipes\` to see all recipes.`);
+            throw new Error(`unknown recipe "${id}". Run \`recursion recipes\` to see all recipes.`);
         }
         const format = opts.format ?? 'cli';
         // `Object.hasOwn`, not `format in RECIPE_FORMATS`: `in` walks the prototype
@@ -577,7 +577,7 @@ function addRecipesCommand(program, manifest, io) {
         io.stdout(renderRecipeShow(entry, format, manifest.recipes));
     });
 }
-/** The full catalog, grouped by category, for `rl recipes`. */
+/** The full catalog, grouped by category, for `recursion recipes`. */
 export function renderRecipeList(reference) {
     const entries = Object.values(reference);
     if (entries.length === 0)
@@ -588,7 +588,7 @@ export function renderRecipeList(reference) {
         group.push(entry);
         byCategory.set(entry.category, group);
     }
-    const lines = ['Recipes — run `rl recipes <id>` for the full walkthrough.', ''];
+    const lines = ['Recipes — run `recursion recipes <id>` for the full walkthrough.', ''];
     for (const category of [...byCategory.keys()].sort()) {
         lines.push(category);
         const group = byCategory.get(category) ?? [];
@@ -649,7 +649,7 @@ export function renderRelatedBlock(entry, allRecipes) {
     }
     return lines.length > 0 ? `Related\n${lines.join('\n')}\n` : '';
 }
-/** One recipe rendered for `rl recipes <id>`: goal + composed code + related links + a docs link. */
+/** One recipe rendered for `recursion recipes <id>`: goal + composed code + related links + a docs link. */
 export function renderRecipeShow(entry, format, allRecipes) {
     // Optional on the wire: an older server predates the Python surface, so
     // `--format py` renders the note rather than crashing on a missing snippet.
@@ -672,7 +672,7 @@ export function renderRecipeShow(entry, format, allRecipes) {
         '',
     ].join('\n');
 }
-/** `rl explain [<concept>]` — Explanation (list grouped by domain, or one page). */
+/** `recursion explain [<concept>]` — Explanation (list grouped by domain, or one page). */
 function addExplainCommand(program, manifest, io) {
     program
         .command('explain [concept]')
@@ -688,14 +688,17 @@ function addExplainCommand(program, manifest, io) {
             ? manifest.concepts[concept]
             : undefined;
         if (!entry) {
-            throw new Error(`unknown concept "${concept}". Run \`rl explain\` to list concepts.`);
+            throw new Error(`unknown concept "${concept}". Run \`recursion explain\` to list concepts.`);
         }
         io.stdout(renderConceptShow(entry));
     });
 }
 function renderConceptList(manifest) {
     const groups = groupByDomain(Object.values(manifest.concepts), (c) => c.domain, manifest.domains);
-    const lines = ['Explanations — run `rl explain <concept>` for the full page.', ''];
+    const lines = [
+        'Explanations — run `recursion explain <concept>` for the full page.',
+        '',
+    ];
     for (const group of groups) {
         lines.push(group.title);
         for (const c of group.entries.sort((a, b) => a.id.localeCompare(b.id, 'en'))) {
@@ -713,7 +716,7 @@ function renderConceptShow(concept) {
     }
     return `${parts.join('\n')}\n`;
 }
-/** `rl tutorials [<id>]` — Tutorials (the existing getting-started docs). */
+/** `recursion tutorials [<id>]` — Tutorials (the existing getting-started docs). */
 function addTutorialsCommand(program, manifest, io) {
     program
         .command('tutorials [id]')
@@ -721,7 +724,10 @@ function addTutorialsCommand(program, manifest, io) {
         .description('Browse getting-started tutorials (run without an argument to list all)')
         .action((id) => {
         if (id === undefined) {
-            const lines = ['Tutorials — run `rl tutorials <id>` for the full text.', ''];
+            const lines = [
+                'Tutorials — run `recursion tutorials <id>` for the full text.',
+                '',
+            ];
             for (const t of manifest.tutorials)
                 lines.push(`  ${t.id} — ${t.title}`);
             io.stdout(`${lines.join('\n')}\n`);
@@ -729,7 +735,7 @@ function addTutorialsCommand(program, manifest, io) {
         }
         const entry = manifest.tutorials.find((t) => t.id === id);
         if (!entry) {
-            throw new Error(`unknown tutorial "${id}". Run \`rl tutorials\` to list tutorials.`);
+            throw new Error(`unknown tutorial "${id}". Run \`recursion tutorials\` to list tutorials.`);
         }
         if (entry.body === null) {
             io.stdout(`${entry.title}\n\nThis tutorial is a notebook — open it in the app: ` +
@@ -741,7 +747,7 @@ function addTutorialsCommand(program, manifest, io) {
 }
 /** The program shell — name, description, version, and the global options. */
 export function buildBaseProgram(version, io) {
-    return (new Command('rl')
+    return (new Command('recursion')
         // Route commander's own output (help text, unknown-command errors, invalid
         // option values) through the caller's sinks, and turn its `process.exit`
         // calls into thrown `CommanderError`s.
@@ -753,13 +759,13 @@ export function buildBaseProgram(version, io) {
         // process streams and still calling `process.exit`.
         .configureOutput({ writeOut: io.stdout, writeErr: io.stderr })
         .exitOverride()
-        .description('Command-line interface for the Recursion RL platform')
+        .description('Command-line interface for the Recursion Platform')
         .version(version)
         .option('--api-key <key>', 'API key (defaults to the LABELBOX_API_KEY env var)')
         .option('--base-url <url>', 'Recursion API base URL (defaults to the RECURSION_BASE_URL env var, then the production host)')
         .option('--quiet', 'Output only the resulting resource id (JSON otherwise)'));
 }
-/** Build the full `rl` program from a fetched manifest. */
+/** Build the full `recursion` program from a fetched manifest. */
 export function buildProgram(manifest, ctx) {
     // `ctx` structurally satisfies CliIo, so the root program — and by inheritance
     // every command built below — writes to the caller's sinks and never exits.
@@ -859,7 +865,7 @@ export function buildProgram(manifest, ctx) {
     for (const [parent, gatedCount] of gatedCountByParent) {
         parent.addHelpText('before', permissionGroupBanner(gatedCount));
     }
-    // The docs browse groups + the bespoke `rl skills` action group.
+    // The docs browse groups + the bespoke `recursion skills` action group.
     addResourcesCommand(program, manifest, ctx);
     addRecipesCommand(program, manifest, ctx);
     addExplainCommand(program, manifest, ctx);
@@ -873,7 +879,7 @@ export function buildProgram(manifest, ctx) {
     // Lazy implicit help skips _initCommandGroup unless created via helpCommand(true).
     program.helpCommand(true);
     program.addHelpText('after', `
-Run \`rl <command> --help\` for details and flags on any command.
-Browse the full reference with \`rl resources\`, or guided walkthroughs with \`rl recipes\`.`);
+Run \`recursion <command> --help\` for details and flags on any command.
+Browse the full reference with \`recursion resources\`, or guided walkthroughs with \`recursion recipes\`.`);
     return program;
 }

package/dist/resolve.d.ts

@@ -4,7 +4,7 @@ export declare function flagValue(argv: string[], name: string): string | undefi
 export declare function resolveApiKey(argv: string[]): string | undefined;
 /**
  * The base URL from the environment: the current `RECURSION_BASE_URL`, else the
- * deprecated `RL_GYM_BASE_URL`. Shared by `resolveBaseUrl` here and the `rl skills`
+ * deprecated `RL_GYM_BASE_URL`. Shared by `resolveBaseUrl` here and the `recursion skills`
  * resolver so the precedence lives — and is tested — in one place.
  */
 export declare function envBaseUrl(): string | undefined;

package/dist/resolve.js

@@ -13,7 +13,7 @@ export function flagValue(argv, name) {
     const index = argv.indexOf(`--${name}`);
     if (index >= 0) {
         // The space-form value is the next token — but only if it isn't itself an
-        // option (`rl --api-key --quiet`): a dangling `--api-key` has no value, so we
+        // option (`recursion --api-key --quiet`): a dangling `--api-key` has no value, so we
         // return undefined and let the env fallback apply rather than silently
         // consuming `--quiet` as a bogus (non-empty) key. Values that legitimately
         // start with `-` use the `--name=value` form above.
@@ -30,7 +30,7 @@ export function resolveApiKey(argv) {
 }
 /**
  * The base URL from the environment: the current `RECURSION_BASE_URL`, else the
- * deprecated `RL_GYM_BASE_URL`. Shared by `resolveBaseUrl` here and the `rl skills`
+ * deprecated `RL_GYM_BASE_URL`. Shared by `resolveBaseUrl` here and the `recursion skills`
  * resolver so the precedence lives — and is tested — in one place.
  */
 export function envBaseUrl() {

package/dist/run.d.ts

@@ -31,7 +31,7 @@ export interface RunDeps {
  *
  * **Never throws and never exits.** It returns the exit code the caller should
  * use, having already rendered any failure to `deps.stderr`. That contract is
- * what lets the MCP endpoint run one `rl` invocation in-process on behalf of an
+ * what lets the MCP endpoint run one `recursion` invocation in-process on behalf of an
  * agent: a thrown error would become a 500 instead of a tool result, and a
  * `process.exit` would take the API server down mid-request. `bin.ts` is the only
  * caller that turns the returned code back into a real exit.

package/dist/run.js

@@ -12,7 +12,7 @@ const MISSING_KEY_MESSAGE = 'missing API key — set LABELBOX_API_KEY or pass --
  *
  * **Never throws and never exits.** It returns the exit code the caller should
  * use, having already rendered any failure to `deps.stderr`. That contract is
- * what lets the MCP endpoint run one `rl` invocation in-process on behalf of an
+ * what lets the MCP endpoint run one `recursion` invocation in-process on behalf of an
  * agent: a thrown error would become a 500 instead of a tool result, and a
  * `process.exit` would take the API server down mid-request. `bin.ts` is the only
  * caller that turns the returned code back into a real exit.

package/dist/skills.d.ts

@@ -41,7 +41,7 @@ export declare function listSkills(opts: {
     apiKey?: string | undefined;
     baseUrl: string;
 }): Promise<SkillSummary[]>;
-/** Programmatic core of `rl skills check` — fetch latest, read installed, compare. */
+/** Programmatic core of `recursion skills check` — fetch latest, read installed, compare. */
 export declare function checkSkill(name: string, opts: {
     apiKey: string;
     baseUrl: string;
@@ -53,7 +53,7 @@ export declare function checkSkill(name: string, opts: {
 /** Raised when `install` refuses to clobber a locally-modified file (no `--force`). */
 export declare class HandEditedError extends Error {
 }
-/** Programmatic core of `rl skills install` — fetch latest and write it (guarded). */
+/** Programmatic core of `recursion skills install` — fetch latest and write it (guarded). */
 export declare function installSkill(name: string, opts: {
     apiKey: string;
     baseUrl: string;

package/dist/skills.js

@@ -6,14 +6,14 @@ import process from 'node:process';
 import { z } from 'zod';
 import { DEFAULT_BASE_URL, supportUrl } from './manifest.js';
 import { envBaseUrl } from './resolve.js';
-// ── bespoke `rl skills` group (hand-written, not spec-derived) ────────────────
+// ── bespoke `recursion skills` group (hand-written, not spec-derived) ────────────────
 //
 // Keeps a downloaded Claude skill current. The platform serves each skill from
 // `GET /skills/:skillName` with a content-hash version; this group fetches that,
 // compares it to the installed `~/.claude/skills/<name>/SKILL.md`, and refreshes
-// it. The skill's own doctor preflight runs `rl skills check` each session and
-// refreshes via `rl skills install` when stale. Deliberately NOT an `@SdkRoute`
-// endpoint — that would auto-generate a colliding `rl skills` command.
+// it. The skill's own doctor preflight runs `recursion skills check` each session and
+// refreshes via `recursion skills install` when stale. Deliberately NOT an `@SdkRoute`
+// endpoint — that would auto-generate a colliding `recursion skills` command.
 /** The skill installed by default when no name is given. */
 const DEFAULT_SKILL = 'recursion';
 // ── hash contract — MUST stay byte-identical to apps/recursion/api/src/skills/skill-hash.ts ──
@@ -79,9 +79,9 @@ function resolveAuth(program) {
     }
     return { apiKey, baseUrl: resolveBaseUrl(program) };
 }
-// Each `rl skills` fetch is bounded for the same reason as the manifest fetch
+// Each `recursion skills` fetch is bounded for the same reason as the manifest fetch
 // (see manifest.ts): a server that accepts the connection but never responds would
-// otherwise hang `rl skills check`/`install`/`list` indefinitely. The timeout makes
+// otherwise hang `recursion skills check`/`install`/`list` indefinitely. The timeout makes
 // `fetch` reject so the caller surfaces a clear error rather than blocking forever.
 const SKILLS_FETCH_TIMEOUT_MS = 30_000;
 /**
@@ -143,7 +143,7 @@ function readInstalled(path) {
         return undefined;
     }
 }
-/** Programmatic core of `rl skills check` — fetch latest, read installed, compare. */
+/** Programmatic core of `recursion skills check` — fetch latest, read installed, compare. */
 export async function checkSkill(name, opts) {
     const latest = await fetchSkill(name, opts.apiKey, opts.baseUrl);
     const installed = readInstalled(installedPath(name, opts.skillFile));
@@ -152,7 +152,7 @@ export async function checkSkill(name, opts) {
 /** Raised when `install` refuses to clobber a locally-modified file (no `--force`). */
 export class HandEditedError extends Error {
 }
-/** Programmatic core of `rl skills install` — fetch latest and write it (guarded). */
+/** Programmatic core of `recursion skills install` — fetch latest and write it (guarded). */
 export async function installSkill(name, opts) {
     const latest = await fetchSkill(name, opts.apiKey, opts.baseUrl);
     const path = installedPath(name, opts.skillFile);
@@ -197,7 +197,7 @@ export function addSkillsCommands(program, docsHelpGroup) {
                 return;
             }
             const lines = available.map((s) => s.description ? `  ${s.name} — ${s.description}` : `  ${s.name}`);
-            process.stdout.write(`Installable skills (run \`rl skills install <name>\`):\n${lines.join('\n')}\n`);
+            process.stdout.write(`Installable skills (run \`recursion skills install <name>\`):\n${lines.join('\n')}\n`);
         }
         catch (err) {
             process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -218,7 +218,7 @@ export function addSkillsCommands(program, docsHelpGroup) {
                 return;
             }
             const lead = status === 'missing' ? 'is not installed' : 'is out of date';
-            process.stdout.write(`${skill} ${lead} — run \`rl skills install ${skill}\`.\n`);
+            process.stdout.write(`${skill} ${lead} — run \`recursion skills install ${skill}\`.\n`);
             process.exit(1);
         }
         catch (err) {

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@labelbox/recursion-cli",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Labelbox/recursion-platform.git"
   },
   "bin": {
+    "recursion": "./dist/bin.js",
     "rl": "./dist/bin.js"
   },
   "files": [