Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(cli): add VHS recording script for CLI demo generation

jkomyno5c6c0ec2c85f
diff --git a/.claude/skills/implement-cli-command/SKILL.md b/.claude/skills/implement-cli-command/SKILL.md
index 12d9a6b38..c1bfd5a61 100644
--- a/.claude/skills/implement-cli-command/SKILL.md
+++ b/.claude/skills/implement-cli-command/SKILL.md
@@ -472,9 +472,59 @@ When implementing a new command:
6. Register in `src/commands/index.ts` (or in the parent group's command file)
7. If using a new service, add its layer to `src/bin.ts`
8. Build to verify: `cd ts/packages/cli && pnpm build`
+9. Add recordings for the new command (see **Recording** below)
If the build fails, check for: (1) missing service imports, (2) `Option<string>` being used where `string` is expected (use `Option.getOrUndefined` or `Option.match`), (3) the command not being exported from its file.
+## Recording
+
+New commands should have VHS recordings for documentation. Recordings produce SVGs and asciicasts that demonstrate the command in action.
+
+### Step 1: Add Entries to recordings.yaml
+
+Add recording entries to `ts/packages/cli/recordings/recordings.yaml` under the appropriate group:
+
+```yaml
+recordings:
+ my-command:
+ - name: help
+ description: Show my-command help
+ command: "composio my-command --help"
+ height: dynamic # Use for commands whose output exceeds 750px
+
+ - name: basic
+ description: Run my-command with default options
+ command: "composio my-command"
+```
+
+Each entry has:
+- `name` — filename for the recording (produces `<name>.svg`, `<name>.ascii`, `<name>.tape`)
+- `command` — the exact shell command to record
+- `description` — (optional) comment shown instantly above the command
+- `sleepAfterEnter` — (optional) override the default wait time after Enter (default: `6s`)
+- `height` — (optional) `'dynamic'` for auto-sizing via two-pass recording, or a fixed pixel number. Omit to use the default height (750px)
+
+Use `height: dynamic` for commands that produce long output (help text, full listings). Fixed height is fine for short-output commands (version, no-results, limited queries).
+
+### Step 2: Run the Recorder
+
+```bash
+cd ts/packages/cli
+bun scripts/record.ts
+```
+
+Requires `COMPOSIO_API_KEY` in the environment and `vhs` + `composio` on `PATH`.
+
+### Output Structure
+
+```
+recordings/
+├── recordings.yaml # Config
+├── tapes/<group>/<name>.tape # Generated VHS tape files (committed)
+├── svgs/<group>/<name>.svg # SVG recordings
+└── ascii/<group>/<name>.ascii # Asciicast recordings
+```
+
## Reference Files
| File | Purpose |
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.md
index b7fb1084f..0f2cf00f0 100644
--- a/ts/packages/cli/AGENTS.md
+++ b/ts/packages/cli/AGENTS.md
@@ -289,3 +289,44 @@ For principles on how to design CLI interactions (arguments, flags, help text, o
- **Claude skill**: `.claude/skills/create-cli/SKILL.md` (standalone, trimmed for Claude Code context)
Use these guidelines when adding new commands, designing flag interfaces, or making UX decisions for the CLI.
+
+---
+
+## Recording CLI Demos
+
+New commands should have VHS recordings for documentation. The recording script produces SVGs and asciicasts that demonstrate the CLI in action.
+
+### Adding Recordings
+
+1. Add entries to `recordings/recordings.yaml` under the appropriate group
+2. Run `bun scripts/record.ts` (requires `COMPOSIO_API_KEY` and `vhs` on PATH)
+
+### Recording Config
+
+Each entry in `recordings.yaml` accepts:
+
+| Field | Required | Description |
+| ----------------- | -------- | --------------------------------------------------------------------------------------- |
+| `name` | Yes | Filename stem (`<name>.svg`, `<name>.ascii`, `<name>.tape`) |
+| `command` | Yes | Shell command to record |
+| `description` | No | Comment shown instantly above the command (via VHS `Hide`/`Show`) |
+| `sleepAfterEnter` | No | Wait time after Enter (default: `6s` from `vhs.sleepAfterEnter`) |
+| `height` | No | `'dynamic'` for two-pass auto-sizing, or a fixed pixel number. Omit for default (750px) |
+
+Use `height: dynamic` for commands with long output (help text, full listings). The recorder probes with 2x height, parses the SVG to measure content, then re-records at the computed height (capped at `vhs.height * 2`).
+
+### Output Structure
+
+```
+recordings/
+├── recordings.yaml # Config
+├── tapes/<group>/<name>.tape # Generated VHS tape files
+├── svgs/<group>/<name>.svg # SVG recordings
+└── ascii/<group>/<name>.ascii # Asciicast recordings
+```
+
+### Key Files
+
+- **Config**: `recordings/recordings.yaml`
+- **Script**: `scripts/record.ts` — Bun + Effect.ts, parallel VHS execution
+- **Shared tape**: `recordings/tapes/shared-config.tape` — common VHS settings (auto-generated)
diff --git a/ts/packages/cli/package.json b/ts/packages/cli/package.json
index 68ce8b09a..99ab2105d 100644
--- a/ts/packages/cli/package.json
+++ b/ts/packages/cli/package.json
@@ -36,7 +36,8 @@
"prepublishOnly": "pnpm run build && pnpm run build:bin",
"typecheck:src": "tsc --noEmit -p ./tsconfig.src.json",
"typecheck:test": "tsc --noEmit -p ./tsconfig.test.json",
- "typecheck": "pnpm run typecheck:src && pnpm run typecheck:test"
+ "typecheck": "pnpm run typecheck:src && pnpm run typecheck:test",
+ "record": "bun run ./scripts/record.ts"
},
"keywords": [
"composio",
diff --git a/ts/packages/cli/scripts/record.ts b/ts/packages/cli/scripts/record.ts
new file mode 100644
index 000000000..6ccd797be
--- /dev/null
+++ b/ts/packages/cli/scripts/record.ts
@@ -0,0 +1,451 @@
+#!/usr/bin/env bun
+
+/**
+ * Record CLI demo SVGs and asciicasts using VHS.
+ *
+ * Usage: `bun scripts/record.ts`
+ *
+ * Reads `recordings/recordings.yaml` and, for each recording entry:
+ * 1. Generates a VHS `.tape` file → `recordings/tapes/<group>/<name>.tape`
+ * 2. Runs VHS to produce an SVG → `recordings/svgs/<group>/<name>.svg`
+ * 3. Runs VHS to produce an asciicast → `recordings/ascii/<group>/<name>.ascii`
+ *
+ * Recordings run in parallel (concurrency = cpu count − 1).
+ * Requires `vhs` and `composio` on PATH, and COMPOSIO_API_KEY in the environment.
+ */
+
+import process from 'node:process';
+import path from 'node:path';
+import os from 'node:os';
+import { Cause, Config, ConfigProvider, Effect, Exit, Logger, Layer, LogLevel, Ref } from 'effect';
+import { BunContext, BunFileSystem, BunRuntime } from '@effect/platform-bun';
+import { FileSystem } from '@effect/platform';
+import type { Teardown } from '@effect/platform/Runtime';
+import { $ } from 'bun';
+import * as p from '@clack/prompts';
+import color from 'picocolors';
+
+// --- Env vars ---
+
+declare module 'bun' {
+ interface Env {
+ COMPOSIO_API_KEY: string;
+ }
+}
+
+/**
+ * Validates that env vars needed by the `composio` cli during VHS recording don't have undefined values.
+ *
+ * @param env - Environment variable dictionary
+ * @throws Error if any env vars have undefined values
+ */
+function validateRequiredEnvVars(env: Record<string, string | undefined> | undefined): void {
+ if (!env) return;
+
+ const missingVars = Object.entries(env)
+ .filter(([, value]) => value === undefined)
+ .map(([key]) => key);
+
+ if (missingVars.length > 0) {
+ throw new Error(
+ `Missing required environment variables: ${missingVars.join(', ')}\n` +
+ `Set these variables before running the tests.`
+ );
+ }
+}
+
+// Env vars to forward into VHS recordings.
+const env = {
+ // Disables Clack interactive decorations so .ascii output is readable.
+ // See https://github.com/bombshell-dev/clack/pull/169
+ CI: 'true',
+ COMPOSIO_API_KEY: Bun.env.COMPOSIO_API_KEY,
+};
+
+validateRequiredEnvVars(env);
+
+// --- Constannts ---
+
+const CONCURRENCY = Math.max(os.cpus().length - 1, 1);
+
+// --- Types ---
+
+interface VhsConfig {
+ shell: string;
+ width: number;
+ height: number;
+ fontSize: number;
+ fontFamily: string;
+ padding: number;
+ theme: string;
+ typingSpeed: string;
+ framerate: number;
+ cursorBlink: boolean;
+ windowBar: string;
+ sleepAfterEnter: string;
+}
+
+interface Recording {
+ name: string;
+ command: string;
+ description?: string;
+ sleepAfterEnter?: string;
+ height?: 'dynamic' | number;
+}
+
+interface RecordingsConfig {
+ vhs: VhsConfig;
+ recordings: Record<string, Recording[]>;
+}
+
+// --- Tape generation ---
+
+function generateSharedTape(vhs: VhsConfig, env: Record<string, string>): string {
+ const lines = [
+ `Require composio`,
+ ...Object.entries(env).map(([k, v]) => `Env ${k} "${v}"`),
+ `Set Shell ${vhs.shell}`,
+ `Set Width ${vhs.width}`,
+ // Height is intentionally omitted — set per-recording tape to support dynamic heights.
+ `Set FontSize ${vhs.fontSize}`,
+ `Set FontFamily "${vhs.fontFamily}"`,
+ `Set Padding ${vhs.padding}`,
+ `Set Theme "${vhs.theme}"`,
+ `Set TypingSpeed ${vhs.typingSpeed}`,
+ `Set Framerate ${vhs.framerate}`,
+ `Set CursorBlink ${vhs.cursorBlink}`,
+ `Set WindowBar ${vhs.windowBar}`,
+ ];
+ return lines.join('\n') + '\n';
+}
+
+function generateRecordingTape(opts: {
+ sharedTapePath: string;
+ outputPaths: string[];
+ command: string;
+ description?: string;
+ sleepAfterEnter: string;
+ height: number;
+}): string {
+ const lines = [`Set Height ${opts.height}`, `Source "${opts.sharedTapePath}"`];
+ lines.push(...opts.outputPaths.map(p => `Output "${p}"`), '');
+
+ if (opts.description) {
+ lines.push('Hide');
+ lines.push(`Type "# ${opts.description}"`);
+ lines.push('Enter');
+ lines.push('Show');
+ }
+
+ lines.push(`Type "${opts.command}"`, 'Sleep 300ms', 'Enter', `Sleep ${opts.sleepAfterEnter}`);
+
+ return lines.join('\n') + '\n';
+}
+
+// --- Dynamic height ---
+
+/** Pixel overhead for window bar + padding + chrome (VHS height 750 → 480px content area). */
+const CHROME_PX = 270;
+
+/**
+ * Parse a VHS-generated SVG to find the maximum `y` attribute from `<text>` elements
+ * in the last animation frame. Returns the pixel offset of the lowest text line.
+ */
+function parseMaxContentY(svg: string): number {
+ // Find the last animation frame (highest translate X value).
+ const frameRe = /<g transform="translate\((\d+),0\)">/g;
+ let maxX = 0;
+ let lastFrameIdx = 0;
+ let m: RegExpExecArray | null;
+ while ((m = frameRe.exec(svg)) !== null) {
+ const x = parseInt(m[1]!, 10);
+ if (x >= maxX) {
+ maxX = x;
+ lastFrameIdx = m.index;
+ }
+ }
+
+ // Slice the last frame (up to the next frame or closing container tag).
+ const nextFrame = svg.indexOf('<g transform="translate(', lastFrameIdx + 1);
+ const frame = svg.slice(lastFrameIdx, nextFrame > lastFrameIdx ? nextFrame : undefined);
+
+ // Find the max y across all <text> elements in that frame.
+ const yRe = /<text y="(\d+)"/g;
+ let maxY = 0;
+ while ((m = yRe.exec(frame)) !== null) {
+ maxY = Math.max(maxY, parseInt(m[1]!, 10));
+ }
+ return maxY;
+}
+
+// --- Progress bar ---
+
+const BAR_SIZE = 30;
+
+function drawBar(current: number, max: number): string {
+ const filled = Math.round((current / max) * BAR_SIZE);
+ const empty = BAR_SIZE - filled;
+ return `${color.green('━'.repeat(filled))}${color.gray('─'.repeat(empty))}`;
+}
+
+// --- Recording ---
+
+function runVhs(tapePath: string, cliRoot: string, label: string) {
+ return Effect.tryPromise({
+ try: async () => {
+ const r = await $`vhs ${tapePath}`.cwd(cliRoot).quiet().nothrow();
+ if (r.exitCode !== 0) {
+ throw new Error(`vhs exited with code ${r.exitCode}\n${r.stderr.toString()}`);
+ }
+ },
+ catch: err => new Error(`Failed to record ${label}: ${err}`),
+ });
+}
+
+function recordCommand(opts: {
+ group: string;
+ recording: Recording;
+ defaultSleepAfterEnter: string;
+ sharedTapePath: string;
+ svgsDir: string;
+ asciiDir: string;
+ tapesDir: string;
+ cliRoot: string;
+ vhsHeight: number;
+}) {
+ return Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const {
+ group,
+ recording,
+ defaultSleepAfterEnter,
+ sharedTapePath,
+ svgsDir,
+ asciiDir,
+ tapesDir,
+ cliRoot,
+ vhsHeight,
+ } = opts;
+ const rel = (absPath: string) => path.relative(cliRoot, absPath);
+ const label = `${group}/${recording.name}`;
+
+ const sleepAfterEnter = recording.sleepAfterEnter ?? defaultSleepAfterEnter;
+ const maxHeight = vhsHeight * 2;
+
+ // Resolve the recording height: explicit number, dynamic (two-pass), or default.
+ let height = vhsHeight;
+ if (typeof recording.height === 'number') {
+ height = recording.height;
+ } else if (recording.height === 'dynamic') {
+ const probeSvgPath = path.join(tapesDir, group, `${recording.name}.probe.svg`);
+ const probeTapePath = path.join(tapesDir, group, `${recording.name}.probe.tape`);
+
+ const probeTape = generateRecordingTape({
+ sharedTapePath: rel(sharedTapePath),
+ outputPaths: [rel(probeSvgPath)],
+ command: recording.command,
+ description: recording.description,
+ sleepAfterEnter,
+ height: maxHeight,
+ });
+ yield* fs.writeFileString(probeTapePath, probeTape);
+ yield* runVhs(probeTapePath, cliRoot, `${label} (probe)`);
+
+ // Parse the probe SVG for the lowest text line in the final frame.
+ const svg = yield* fs.readFileString(probeSvgPath);
+ const maxY = parseMaxContentY(svg);
+ height = Math.min(Math.max(maxY + CHROME_PX, vhsHeight), maxHeight);
+
+ yield* Effect.logDebug(`[probe] ${label}: maxY=${maxY} → height=${height}`);
+
+ // Clean up probe artifacts.
+ yield* fs.remove(probeSvgPath).pipe(Effect.orElse(() => Effect.void));
+ yield* fs.remove(probeTapePath).pipe(Effect.orElse(() => Effect.void));
+ }
+
+ // Final recording pass (or the only pass for fixed-height recordings).
+ const tapeContent = generateRecordingTape({
+ sharedTapePath: rel(sharedTapePath),
+ outputPaths: [
+ rel(path.join(svgsDir, group, `${recording.name}.svg`)),
+ rel(path.join(asciiDir, group, `${recording.name}.ascii`)),
+ ],
+ command: recording.command,
+ description: recording.description,
+ sleepAfterEnter,
+ height,
+ });
+
+ const tapePath = path.join(tapesDir, group, `${recording.name}.tape`);
+ yield* fs.writeFileString(tapePath, tapeContent);
+ yield* runVhs(tapePath, cliRoot, label);
+ });
+}
+
+function recordAll() {
+ return Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+
+ yield* Effect.sync(() => p.intro('composio record'));
+
+ // Tape-embedded paths are relative to the cli package root (ts/packages/cli/).
+ const scriptDir = path.resolve(
+ import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname)
+ );
+ const cliRoot = path.resolve(scriptDir, '..');
+ const recordingsDir = path.resolve(scriptDir, '..', 'recordings');
+ const configPath = path.join(recordingsDir, 'recordings.yaml');
+
+ yield* Effect.logDebug(`Reading config from ${configPath}`);
+
+ const configRaw = yield* fs.readFileString(configPath);
+ const config = Bun.YAML.parse(configRaw) as RecordingsConfig;
+
+ // Output directories for generated tapes, SVGs, and asciicasts.
+ const tapesDir = path.join(recordingsDir, 'tapes');
+ const svgsDir = path.join(recordingsDir, 'svgs');
+ const asciiDir = path.join(recordingsDir, 'ascii');
+ yield* fs.makeDirectory(tapesDir, { recursive: true });
+ yield* fs.makeDirectory(svgsDir, { recursive: true });
+ yield* fs.makeDirectory(asciiDir, { recursive: true });
+
+ // Write shared config tape.
+ const sharedTapePath = path.join(tapesDir, 'shared-config.tape');
+ yield* fs.writeFileString(sharedTapePath, generateSharedTape(config.vhs, env));
+
+ yield* Effect.sync(() =>
+ p.log.step(`Loaded config from ${color.dim(path.relative(process.cwd(), configPath))}`)
+ );
+
+ // Flatten all recordings across groups.
+ const groups = Object.entries(config.recordings);
+ const allRecordings = groups.flatMap(([group, recordings]) =>
+ recordings.map(recording => ({ group, recording }))
+ );
+ const total = allRecordings.length;
+
+ // Create all group directories upfront.
+ const groupNames = [...new Set(groups.map(([g]) => g))];
+ yield* Effect.forEach(
+ groupNames,
+ group =>
+ Effect.all([
+ fs.makeDirectory(path.join(svgsDir, group), { recursive: true }),
+ fs.makeDirectory(path.join(asciiDir, group), { recursive: true }),
+ fs.makeDirectory(path.join(tapesDir, group), { recursive: true }),
+ ]),
+ { concurrency: 'unbounded' }
+ );
+
+ // Record all with bounded concurrency and a single progress spinner.
+ yield* Effect.sync(() =>
+ p.log.step(
+ `Recording ${color.bold(String(total))} commands ${color.dim(`(concurrency: ${CONCURRENCY})`)}`
+ )
+ );
+ const completed = yield* Ref.make(0);
+ const spin = p.spinner();
+ yield* Effect.sync(() => spin.start(`${drawBar(0, total)} ${color.dim(`0/${total}`)}`));
+
+ yield* Effect.forEach(
+ allRecordings,
+ ({ group, recording }) =>
+ recordCommand({
+ group,
+ recording,
+ defaultSleepAfterEnter: config.vhs.sleepAfterEnter,
+ sharedTapePath,
+ svgsDir,
+ asciiDir,
+ tapesDir,
+ cliRoot,
+ vhsHeight: config.vhs.height,
+ }).pipe(
+ Effect.tap(() =>
+ Ref.updateAndGet(completed, c => c + 1).pipe(
+ Effect.tap(n =>
+ Effect.sync(() =>
+ spin.message(
+ `${drawBar(n, total)} ${color.dim(`${n}/${total}`)} ${group}/${recording.name}`
+ )
+ )
+ )
+ )
+ ),
+ Effect.tapError(err =>
+ Ref.get(completed).pipe(
+ Effect.tap(n =>
+ Effect.sync(() => {
+ spin.error(
+ `${drawBar(n, total)} ${color.bold(group)} failed at ${recording.name}`
+ );
+ p.log.error(String(err));
+ })
+ )
+ )
+ )
+ ),
+ { concurrency: CONCURRENCY }
+ );
+
+ yield* Effect.sync(() =>
+ spin.stop(`${drawBar(total, total)} ${color.dim(`${total}/${total}`)} ${color.green('done')}`)
+ );
+
+ // Collect file sizes.
+ let totalBytes = 0n;
+ for (const { group, recording } of allRecordings) {
+ for (const filePath of [
+ path.join(svgsDir, group, `${recording.name}.svg`),
+ path.join(asciiDir, group, `${recording.name}.ascii`),
+ ]) {
+ const stat = yield* fs
+ .stat(filePath)
+ .pipe(Effect.orElse(() => Effect.succeed({ size: 0n } as { size: bigint })));
+ totalBytes += BigInt(stat.size);
+ }
+ }
+
+ const totalKB = (Number(totalBytes) / 1024).toFixed(1);
+
+ yield* Effect.sync(() =>
+ p.note(
+ [
+ `${color.bold(String(total))} recordings`,
+ `${color.bold(totalKB)} KB total`,
+ color.dim(`${path.relative(process.cwd(), recordingsDir)}/`),
+ ].join('\n'),
+ 'Summary'
+ )
+ );
+
+ yield* Effect.sync(() => p.outro('Recording complete'));
+ });
+}
+
+// --- Bootstrap ---
+
+export const teardown: Teardown = <E, A>(exit: Exit.Exit<E, A>, onExit: (code: number) => void) => {
+ const shouldFail = Exit.isFailure(exit) && !Cause.isInterruptedOnly(exit.cause);
+ const errorCode = Number(process.exitCode ?? 1);
+ onExit(shouldFail ? errorCode : 0);
+};
+
+const ConfigLive = Effect.gen(function* () {
+ const logLevel = yield* Config.logLevel('COMPOSIO_LOG_LEVEL').pipe(
+ Config.withDefault(LogLevel.Info)
+ );
+
+ return Logger.minimumLogLevel(logLevel);
+}).pipe(Layer.unwrapEffect, Layer.merge(Layer.setConfigProvider(ConfigProvider.fromEnv())));
+
+recordAll().pipe(
+ Effect.provide(ConfigLive),
+ Effect.provide(Logger.pretty),
+ Effect.provide(BunContext.layer),
+ Effect.provide(BunFileSystem.layer),
+ Effect.map(() => ({ message: 'Process completed successfully.' })),
+ BunRuntime.runMain({
+ teardown,
+ })
+);
diff --git a/turbo.jsonc b/turbo.jsonc
index 4fdc0c53d..9741ce1fc 100644
--- a/turbo.jsonc
+++ b/turbo.jsonc
@@ -51,6 +51,20 @@
},
"//#clean": {
"cache": false
+ },
+ "record": {
+ "dependsOn": ["^build"],
+ "inputs": [
+ "src/**",
+ "scripts/record.ts",
+ "recordings/recordings.yaml"
+ ],
+ "outputs": [
+ "recordings/tapes/**",
+ "recordings/svgs/**",
+ "recordings/ascii/**"
+ ],
+ "env": ["COMPOSIO_API_KEY"]
}
}
}