@rayrun/cli 0.3.0 → 0.5.0

package/README.md

@@ -1,17 +1,19 @@
 # @rayrun/cli
 
-Connect supported MCP clients, execute approved tools through OAuth, and manage Rayrun through its
-public API.
+Build and deploy complete MCP servers, connect supported MCP clients, execute approved tools through
+OAuth, and manage Rayrun through its public API.
 
 ```sh
 pnpm --package @rayrun/cli@latest dlx rayrun setup https://copy-the-endpoint-from-rayrun.example/mcp
 ```
 
-The command detects Claude Code, Codex/ChatGPT desktop, Cursor, VS Code, Windsurf/Devin Local, and OpenCode v2. It shows the detected clients before changing anything. Pass `--client cursor` more than once for automation, or `--all --yes` to configure every detected client.
+The command detects Claude Code, Codex/ChatGPT desktop, Cursor, VS Code, Windsurf/Devin Local, and
+OpenCode v2. It shows the targets before writing. Repeat `--client` to select targets, or use
+`--all --yes` to configure all detected clients.
 
-It writes only the public Rayrun endpoint. OAuth stays inside each client; no bearer token or API key is put in a config file or shell history. Before changing configuration it stores byte-for-byte backups under `~/.rayrun/backups/setup`, writes JSON atomically, and restores every target if a configuration write fails. A later client-login failure leaves the valid configuration in place and prints the exact login command to retry.
-
-Backups are private to your user account (`0700` directories and `0600` files) and are retained until you remove old backup directories after their rollback window is no longer useful.
+It writes only the public Rayrun endpoint. OAuth stays in each client; no token or API key enters a
+config file or shell history. Before writing, it creates private byte-for-byte backups under
+`~/.rayrun/backups/setup`. Configuration writes are atomic and roll back together on failure.
 
 ```sh
 rayrun setup <endpoint> --dry-run --all
@@ -20,9 +22,13 @@ rayrun setup <endpoint> --client codex --yes --login
 rayrun setup rollback <backup-id>
 ```
 
-Use `--project` for project-local configuration in Claude Code, Codex, Cursor, VS Code, Devin, and OpenCode. Legacy Windsurf remains user-scoped. Claude Code asks you to approve a project MCP server when that project opens. Codex loads `.codex/config.toml` only after you trust the project; restart Codex after doing so.
+Use `--project` for project-local configuration in Claude Code, Codex, Cursor, VS Code, Devin, and
+OpenCode. Legacy Windsurf remains user-scoped. Claude Code asks you to approve a project MCP server
+when the project opens. Codex loads `.codex/config.toml` after you trust the project; restart Codex
+after doing so.
 
-Interactive setup runs supported clients' OAuth login commands. `--yes` and non-interactive setup never launch login unless you explicitly pass `--login`; the command prints the exact login command when it skips one. Pass `--no-login` to make the choice explicit in scripts.
+Interactive setup runs supported OAuth login commands. `--yes` and non-interactive setup skip login
+unless you pass `--login`; use `--no-login` in scripts.
 
 ## Execute tools
 
@@ -52,14 +58,86 @@ Approve in the browser, then run the printed command. `resume` replays only the
 server-issued continuation state; its `accept` response cannot authorize the call without the
 authenticated browser decision. Pending files can contain the exact tool arguments and are stored
 under `~/.rayrun/execution/pending`. The resume window expires after 10 minutes; expired files are
-pruned by the next execution command and are also removed by `rayrun logout`. OAuth refresh tokens
-use the same account-private storage. `RAYRUN_CONFIG_HOME` must use a local, per-host filesystem.
-POSIX systems enforce `0700` directories and `0600` files. On Windows, execution storage must remain
-inside the current user profile and inherits that profile's ACL. `logout` removes tokens locally and
-attempts token revocation.
+pruned by the next execution command or `rayrun logout`. OAuth tokens use the same private,
+per-host storage; keep `RAYRUN_CONFIG_HOME` on a local filesystem. POSIX systems enforce `0700`
+directories and `0600` files; Windows uses the current profile's ACL. `logout` removes local tokens
+and attempts revocation.
+
+## Build and deploy an MCP server
+
+`rayrun init` creates a complete TypeScript MCP server using Node.js 24,
+[ViteMCP](https://github.com/vitemcp/server), Zod, and Vitest. Give the generated directory to Codex,
+Claude Code, or another coding agent and ask it to implement the server—not just one tool. The
+server may expose as many tools as the project needs, up to the release limit documented below.
+
+```sh
+rayrun init my-mcp
+cd my-mcp
+npm test
+export RAYRUN_API_KEY='rak_...'
+rayrun deploy --wait
+```
+
+On first deploy, Rayrun creates the service and saves its connection UID in
+`.rayrun/project.json`. Later deploys update that same service. Use `--connection` to target a
+different existing source deployment, and declare required secret names in `rayrun.json`:
+
+```sh
+rayrun deploy --secret GITHUB_TOKEN=<workspace-secret-uid> --wait
+rayrun deployments list --connection <connection-uid>
+rayrun deployments logs <build-uid>
+rayrun deployments releases <connection-uid>
+rayrun deployments rollback <connection-uid> <release-uid> --wait
+```
+
+The generated `rayrun.json` is the deployment contract. Visible configuration belongs in
+`environment`; required secret environment names belong in `secrets` and are bound to
+workspace-secret UIDs at deploy time:
+
+```json
+{
+  "entrypoint": "dist/server.js",
+  "environment": {
+    "INVOICE_API_URL": "https://api.example.com"
+  },
+  "name": "invoice-automation",
+  "secrets": ["INVOICE_API_TOKEN"],
+  "version": 1
+}
+```
+
+The project root must also contain `package.json` with `"type": "module"` and a build script, plus
+`package-lock.json`. The built server must listen on `PORT` and expose Streamable HTTP MCP at
+`/mcp`. `NODE_ENV`, `PORT`, and `RAYRUN_DEPLOYMENT_UID` are reserved.
+
+The recommended scaffold is a golden path, not a platform lock-in. Rayrun accepts a Node project
+with a lockfile and build script whose configured entrypoint serves Streamable HTTP MCP at `/mcp`
+on `PORT`. Source uploads reject symlinks, a Dockerfile, `.env` files, obvious private-key material,
+more than 512 files, or more than 16 MiB. Source is encrypted at rest. Builds run remotely with a
+fixed Node 24 Dockerfile whose runtime stage uses a non-root user, and activation happens only after
+the candidate returns at least one tool from `tools/list`. A failed candidate leaves the active
+release untouched.
+
+Build logs are encrypted with the workspace data key and erased after 30 days. API keys need the
+separate `deployments:logs:read` scope to read them.
+The Dashboard's **Deploy services** key preset grants only the three deployment scopes required by
+this CLI workflow.
+
+Rotating a bound workspace secret marks the source service for redeploy. Running `rayrun deploy
+--wait` again reuses the already-built image, verifies a candidate with the new secret version, and
+activates it without uploading the secret value or rebuilding unchanged source.
+
+`--wait` follows the exact release UID returned by Rayrun when a built image is reused. Source
+images are limited to 512 MiB, workspace image retention is limited to 5 GiB, and inactive images
+remain available for rollback for 30 days.
+
+A workspace can hold 25 source-deployed services, run 10 source builds concurrently, and start 50
+isolated builds in 24 hours. One service can build at a time. A release may advertise up to 1,000
+tools; build logs are capped at 1 MiB and erased after 30 days.
 
-Execution lock errors print the exact generation file to remove if a process crashed and its PID was
-reused. Remove that file only after verifying that no Rayrun CLI execution command is still running.
+Private package-manager credentials are not accepted: `.npmrc` and Yarn credential files are
+excluded locally and rejected by the API. Build dependencies must be readable without placing a
+registry token in the uploaded project.
 
 ## Manage a workspace
 
@@ -73,6 +151,21 @@ export RAYRUN_API_KEY='rak_...'
 rayrun connect mcp https://mcp.example.com --name 'Internal tools'
 rayrun connect openapi https://api.example.com/openapi.json --name 'Example API'
 rayrun connections list
+rayrun connections history <connection-uid>
+rayrun connections diff <connection-uid> <version-uid>
+rayrun connections restore <connection-uid> <version-uid> --reason 'Restore reviewed settings'
+rayrun access-profiles list
+rayrun access-profiles history <profile-uid>
+rayrun access-profiles diff <profile-uid> <version-uid>
+rayrun access-profiles restore <profile-uid> <version-uid> \
+  --reason 'Restore reviewed policy' --confirm-risk
+rayrun webhooks list
+rayrun webhooks update <webhook-uid> --config '{"enabled":false}' \
+  --reason 'Pause deliveries during maintenance'
+rayrun webhooks history <webhook-uid>
+rayrun webhooks diff <webhook-uid> <version-uid>
+rayrun webhooks restore <webhook-uid> <version-uid> \
+  --reason 'Restore reviewed destination'
 rayrun clients list
 rayrun tools search create issue --connection <connection-uid>
 rayrun policy inspect <client-uid> --query issue
@@ -84,3 +177,93 @@ List commands show a compact table. Add `--json` for stable machine-readable out
 request up to 100 rows, and `--cursor` with the printed next cursor to continue. The CLI calls the
 same hosted API and policy evaluator as the dashboard; it does not run a local gateway or store API
 keys.
+
+Connection history versions the service name, slug, description, timeout, enablement, and payload
+capture together. Credentials, headers, OAuth state, authority policy, health, and index state never
+enter the snapshot. `history` is cursor-paginated, `diff` compares with the immediate predecessor,
+and `restore` creates a new attributed version using optimistic concurrency.
+
+Access-profile history versions the name, description, default, and exact tool rules together.
+Client assignments and archival remain separate authorization events. Restore refuses references to
+tools that are no longer available; pass `--confirm-risk` only after reviewing every Destructive or
+Unknown tool allowed by the restored default or an exact rule. Immutable access-profile history is
+limited to 64 MiB per workspace.
+
+Webhook history versions the destination URL, description, event selection, delivery mode, batch
+size, enablement, and payload forwarding together. Signing secrets, deliveries, retry state, and
+health never enter the snapshot. Restore revalidates the historical destination, creates a new
+attributed version, and preserves the current signing secret. Immutable webhook history is limited
+to 64 MiB per workspace. Destination paths and query strings can contain provider tokens, so
+`diff` requires `webhooks:read`; add `webhooks:write` to reveal full destination URLs. Read-only
+API keys receive `null` instead of current or historical URLs.
+
+## Publish Workspace Skills
+
+Workspace Skills are Agent Skills packages delivered by compatible clients through Rayrun's
+SEP-2640 MCP extension. The package root must contain `SKILL.md`; local reads reject symlinks,
+special files, unsafe paths, more than 512 files, or more than 16 MiB.
+
+```sh
+rayrun skills validate ./skills/incident-response
+rayrun skills push ./skills/incident-response --publish \
+  --mode both --all-clients --reason 'Reviewed for production use'
+rayrun skills list
+rayrun skills show <skill-uid>
+rayrun skills audience <skill-uid> --mode direct --profiles <profile-uid>
+rayrun skills history <skill-uid>
+rayrun skills diff <skill-uid> <version-uid>
+rayrun skills pull <skill-uid> --output ./recovered-skill
+rayrun skills restore <skill-uid> <version-uid> --reason 'Recover reviewed instructions'
+rayrun skills disable <skill-uid>
+rayrun skills archive <skill-uid>
+rayrun skills delete <skill-uid> --confirm-name incident-response
+```
+
+`push` saves a draft unless `--publish` is explicit. A new draft never moves the existing published
+pointer. Pass `--profiles` as comma-separated access-profile UIDs to narrow discovery, or explicitly
+pass `--all-clients`. Later publish and audience commands preserve the current audience when both
+flags are omitted. Script, binary-file, and possible-secret warnings require
+`--confirm-risk` before publication. `allowed-tools` is guidance, not access policy.
+
+`pull` refuses to overwrite an existing path and creates account-private directories and files.
+Restore creates another immutable draft revision and does not publish it. Permanent deletion removes
+all content and delivery summaries, cannot be undone, and keeps the Skill name reserved so an old
+`skill://` URI cannot resolve to unrelated content.
+
+## Author hosted tool hooks
+
+Use a full-control API key. Hook source executes in Rayrun’s hosted sandbox, not in the CLI process.
+
+```sh
+rayrun hooks pull <connection-uid> <tool-uid> \
+  --output hook.ts --types-output rayrun-hooks.d.ts
+
+rayrun hooks test <connection-uid> <tool-uid> \
+  --file hook.ts --arguments '{"query":"release"}' --mock-result '{"items":[]}'
+
+rayrun hooks save <connection-uid> <tool-uid> \
+  --file hook.ts --reason 'Normalize release results'
+rayrun hooks history <connection-uid> <tool-uid>
+rayrun hooks diff <connection-uid> <tool-uid> <draft-version-uid>
+rayrun hooks restore <connection-uid> <tool-uid> <draft-version-uid> \
+  --reason 'Restore the reviewed mapping'
+rayrun hooks reset <connection-uid> <tool-uid> --confirm <hook-uid>@<version> \
+  --reason 'Remove obsolete experiment history'
+rayrun hooks deploy <connection-uid> <tool-uid> --shadow
+rayrun hooks logs <connection-uid> <tool-uid>
+rayrun hooks rollback <connection-uid> <tool-uid> <revision-uid>
+rayrun hooks deactivate <connection-uid> <tool-uid> --shadow
+```
+
+`pull` can write the draft and generated TypeScript declarations separately. `test` compiles and
+runs before plus an optional after stage using your mock result; it never contacts the upstream.
+Each material `save` creates an immutable, attributed draft version; identical saves do not create
+noise. `history` is paginated, `diff` compares with the previous version, and `restore` creates a
+new draft head. Draft history and deployment revisions remain separate. Source and config history
+is limited to 64 MiB per workspace.
+
+`reset` permanently removes the hook's history and deployment revisions using the current hook UID
+and version. A connection cannot be deleted while it owns hook history. `deploy` creates an
+immutable revision and defaults to active; rollback and deactivate also accept `--shadow`. Hook
+payloads follow the service capture setting, while timing, outcome, revision, request ID, and shadow
+comparison remain available. Captured details require a full-control key.

package/index.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 
 import { main } from './src/main.js';
+import { sanitizeTerminalError } from './src/sanitizeTerminalError.js';
 
 try {
   await main(process.argv.slice(2));
 } catch (error) {
-  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.stderr.write(
+    `${sanitizeTerminalError(error instanceof Error ? error.message : String(error))}\n`,
+  );
   process.exitCode = 1;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rayrun/cli",
-  "version": "0.3.0",
-  "description": "Set up MCP clients, execute tools, and manage Rayrun from the command line",
+  "version": "0.5.0",
+  "description": "Build and deploy MCP servers, connect clients, execute tools, and manage Rayrun",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,11 +15,14 @@
     "index.js",
     "src/clients.js",
     "src/config.js",
+    "src/deployments.js",
     "src/execution.js",
     "src/main.js",
     "src/management.js",
     "src/oauth.js",
+    "src/sanitizeTerminalError.js",
     "src/setup.js",
+    "src/skills.js",
     "README.md",
     "LICENSE"
   ],
@@ -29,12 +32,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/client": "2.0.0",
-    "@rayrun/sdk": "^0.4.0",
+    "@rayrun/sdk": "^0.7.0",
+    "diff": "^9.0.0",
+    "ignore": "7.0.6",
     "jsonc-parser": "^3.3.1",
     "smol-toml": "^1.8.0"
   },
   "devDependencies": {
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=20"

package/src/deployments.js

@@ -0,0 +1,233 @@
+import createIgnore from 'ignore';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const DEFAULT_IGNORES = [
+  '.git/',
+  '.rayrun/',
+  '.dockerignore',
+  '.env',
+  '.env.*',
+  '.npmrc',
+  '.yarnrc',
+  '.yarnrc.yml',
+  '!.env.example',
+  '!.env.sample',
+  '!.env.template',
+  'coverage/',
+  'dist/',
+  'node_modules/',
+];
+const MAX_SOURCE_BYTES = 16_777_216;
+const MAX_SOURCE_FILES = 512;
+
+const packageJsonFor = (name) => ({
+  dependencies: { '@vitemcp/server': '1.6.5', zod: '4.4.3' },
+  devDependencies: {
+    '@types/node': '26.1.1',
+    tsx: '4.23.12',
+    typescript: '6.0.2',
+    vitest: '4.1.10',
+  },
+  engines: { node: '>=24' },
+  name,
+  private: true,
+  scripts: {
+    build: 'tsc -p tsconfig.json',
+    dev: 'tsx watch src/server.ts',
+    start: 'node dist/server.js',
+    test: 'vitest run',
+  },
+  type: 'module',
+  version: '1.0.0',
+});
+
+const scaffoldFiles = (name) => ({
+  '.gitignore': 'node_modules/\ndist/\ncoverage/\n.env\n.env.*\n!.env.example\n.rayrun/\n',
+  'README.md': `# ${name}\n\nA stateless MCP server built with [ViteMCP](https://github.com/vitemcp/server) and ready for Rayrun.\n\n\`\`\`sh\nnpm test\nnpm run build\nnpx --yes rayrun@latest deploy --wait\n\`\`\`\n`,
+  'package.json': `${JSON.stringify(packageJsonFor(name), null, 2)}\n`,
+  'rayrun.json': `${JSON.stringify(
+    { entrypoint: 'dist/server.js', environment: {}, name, secrets: [], version: 1 },
+    null,
+    2,
+  )}\n`,
+  'src/greet.ts': `export const greet = (name: string) => \`Hello, \${name}!\`;\n`,
+  'src/greet.test.ts': `import { greet } from './greet.js';\nimport { expect, test } from 'vitest';\n\ntest('greets the requested name', () => {\n  expect(greet('Rayrun')).toBe('Hello, Rayrun!');\n});\n`,
+  'src/server.ts': `import { ViteMCP } from '@vitemcp/server';\nimport { z } from 'zod';\nimport { greet } from './greet.js';\n\nconst server = new ViteMCP({ name: '${name}', version: '1.0.0' });\n\nserver.addTool({\n  annotations: { readOnlyHint: true },\n  description: 'Return a friendly greeting.',\n  execute: async ({ name }) => greet(name),\n  name: 'greet',\n  parameters: z.object({ name: z.string().min(1).describe('Name to greet') }),\n});\n\nawait server.start({\n  httpStream: { endpoint: '/mcp', port: Number.parseInt(process.env.PORT ?? '8080', 10) },\n  transportType: 'httpStream',\n});\n`,
+  'tsconfig.json': `${JSON.stringify(
+    {
+      compilerOptions: {
+        declaration: true,
+        esModuleInterop: true,
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        noUncheckedIndexedAccess: true,
+        outDir: 'dist',
+        rootDir: 'src',
+        strict: true,
+        target: 'ES2023',
+        types: ['node'],
+      },
+      exclude: ['dist', 'node_modules', 'src/**/*.test.ts'],
+      include: ['src/**/*.ts'],
+    },
+    null,
+    2,
+  )}\n`,
+});
+
+const runNpmInstall = async (directory) => {
+  await new Promise((resolve, reject) => {
+    const child = spawn('npm', ['install', '--ignore-scripts'], {
+      cwd: directory,
+      stdio: 'inherit',
+    });
+    child.once('error', reject);
+    child.once('exit', (code) =>
+      code === 0 ? resolve() : reject(new Error(`npm install exited with code ${String(code)}.`)),
+    );
+  });
+};
+
+const validateDeploymentName = (value) => {
+  const name = value.trim().toLowerCase();
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name) || name.length > 64) {
+    throw new Error('--name must be a lowercase kebab-case name of at most 64 characters.');
+  }
+  return name;
+};
+
+export const scaffoldDeploymentProject = async ({ directory, install = true, name }) => {
+  const destination = path.resolve(directory);
+  const projectName = validateDeploymentName(name ?? path.basename(destination));
+  try {
+    await lstat(destination);
+    throw new Error(`Refusing to overwrite existing path: ${destination}`);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  await mkdir(destination, { recursive: true });
+  const files = scaffoldFiles(projectName);
+  for (const [relativePath, content] of Object.entries(files)) {
+    const filePath = path.join(destination, relativePath);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, content, { flag: 'wx', mode: 0o600 });
+  }
+  if (install) await runNpmInstall(destination);
+  return {
+    directory: destination,
+    fileCount: Object.keys(files).length + (install ? 1 : 0),
+    name: projectName,
+  };
+};
+
+const optionalText = async (filePath) => {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return '';
+    throw error;
+  }
+};
+
+export const readDeploymentDirectory = async (directory) => {
+  const root = path.resolve(directory);
+  const rootStat = await lstat(root);
+  if (!rootStat.isDirectory()) throw new Error(`${root} is not a directory.`);
+  const hardIgnored = createIgnore().add(DEFAULT_IGNORES);
+  const projectIgnored = createIgnore();
+  projectIgnored.add(await optionalText(path.join(root, '.gitignore')));
+  projectIgnored.add(await optionalText(path.join(root, '.dockerignore')));
+  const files = [];
+  let byteCount = 0;
+
+  const walk = async (relativeDirectory = '') => {
+    const entries = await readdir(path.join(root, relativeDirectory), { withFileTypes: true });
+    for (const entry of entries.toSorted((left, right) => left.name.localeCompare(right.name))) {
+      const relativePath = path.posix.join(relativeDirectory.split(path.sep).join('/'), entry.name);
+      const ignorePath = entry.isDirectory() ? `${relativePath}/` : relativePath;
+      if (hardIgnored.ignores(ignorePath) || projectIgnored.ignores(ignorePath)) continue;
+      if (entry.isSymbolicLink())
+        throw new Error(`Source symlinks are not allowed: ${relativePath}`);
+      if (entry.isDirectory()) {
+        await walk(relativePath);
+        continue;
+      }
+      if (!entry.isFile()) throw new Error(`Unsupported source file type: ${relativePath}`);
+      const bytes = await readFile(path.join(root, relativePath));
+      byteCount += bytes.byteLength;
+      if (files.length + 1 > MAX_SOURCE_FILES) {
+        throw new Error(`Source contains more than ${String(MAX_SOURCE_FILES)} files.`);
+      }
+      if (byteCount > MAX_SOURCE_BYTES) {
+        throw new Error('Source is larger than 16 MiB.');
+      }
+      files.push({ contentBase64: bytes.toString('base64'), path: relativePath });
+    }
+  };
+  await walk();
+  return files;
+};
+
+export const readDeploymentProjectState = async (directory) => {
+  try {
+    const stateDirectory = path.join(directory, '.rayrun');
+    const stateDirectoryStat = await lstat(stateDirectory);
+    if (!stateDirectoryStat.isDirectory() || stateDirectoryStat.isSymbolicLink()) {
+      throw new Error('.rayrun must be a real directory.');
+    }
+    const statePath = path.join(stateDirectory, 'project.json');
+    const stateStat = await lstat(statePath);
+    if (!stateStat.isFile() || stateStat.isSymbolicLink()) {
+      throw new Error('.rayrun/project.json must be a regular file.');
+    }
+    const parsed = JSON.parse(await readFile(statePath, 'utf8'));
+    return typeof parsed.connectionUid === 'string' ? parsed : null;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw new Error(
+      '.rayrun/project.json is invalid. Remove it or provide --connection explicitly.',
+    );
+  }
+};
+
+export const writeDeploymentProjectState = async (directory, connectionUid) => {
+  const stateDirectory = path.join(directory, '.rayrun');
+  try {
+    const state = await lstat(stateDirectory);
+    if (!state.isDirectory() || state.isSymbolicLink()) {
+      throw new Error('.rayrun must be a real directory.');
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    await mkdir(stateDirectory, { mode: 0o700 });
+  }
+  const statePath = path.join(stateDirectory, 'project.json');
+  const temporaryPath = path.join(stateDirectory, `.project-${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify({ connectionUid, version: 1 }, null, 2)}\n`, {
+      flag: 'wx',
+      mode: 0o600,
+    });
+    await rename(temporaryPath, statePath);
+  } catch (error) {
+    await unlink(temporaryPath).catch(() => undefined);
+    throw error;
+  }
+};
+
+export const parseSecretBindings = (values = []) => {
+  const bindings = {};
+  for (const value of values) {
+    const separator = value.indexOf('=');
+    if (separator <= 0 || separator === value.length - 1) {
+      throw new Error('--secret must use NAME=workspace-secret-uid.');
+    }
+    const name = value.slice(0, separator);
+    if (Object.hasOwn(bindings, name)) throw new Error(`${name} can only be bound once.`);
+    bindings[name] = value.slice(separator + 1);
+  }
+  return bindings;
+};

package/src/main.js

@@ -1,4 +1,5 @@
 import { clientDefinitions, detectClients } from './clients.js';
+import { scaffoldDeploymentProject } from './deployments.js';
 import { executionUsage, isExecutionCommand, runExecutionCommand } from './execution.js';
 import { isManagementCommand, managementUsage, runManagementCommand } from './management.js';
 import { applySetup, rollbackSetup } from './setup.js';
@@ -8,6 +9,7 @@ import { createInterface } from 'node:readline/promises';
 const packageVersion = createRequire(import.meta.url)('../package.json').version;
 
 const usage = `Usage:
+  rayrun init <directory> [--name <kebab-case-name>] [--no-install]
   rayrun setup <endpoint> [--client <id> ... | --all] [--project] [--yes] [--dry-run] [--login | --no-login]
   rayrun setup rollback <backup-id>
 
@@ -112,6 +114,30 @@ export const main = async (arguments_, dependencies) => {
     process.stdout.write(`${String(packageVersion)}\n`);
     return;
   }
+  if (arguments_[0] === 'init') {
+    const directory = arguments_[1];
+    if (!directory || directory.startsWith('--')) {
+      throw new Error(usage);
+    }
+    let name;
+    let install = true;
+    for (let index = 2; index < arguments_.length; index += 1) {
+      const argument = arguments_[index];
+      if (argument === '--no-install') install = false;
+      else if (argument === '--name') {
+        if (name !== undefined) throw new Error('--name can only be provided once.');
+        name = arguments_[index + 1];
+        if (!name || name.startsWith('--')) throw new Error('--name requires a value.');
+        index += 1;
+      } else throw new Error(`Unknown option: ${String(argument)}`);
+    }
+    const created = await scaffoldDeploymentProject({ directory, install, name });
+    const output = dependencies?.output ?? process.stdout;
+    output.write(
+      `Created ${created.name} in ${created.directory}.\nNext: cd ${created.directory} && rayrun deploy --wait\n`,
+    );
+    return;
+  }
   if (isExecutionCommand(arguments_)) {
     await runExecutionCommand(arguments_, { ...dependencies, version: packageVersion });
     return;