runcloud 0.1.2

package/dist/commands/login.js

@@ -0,0 +1,173 @@
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { clearCredentials, credentialsDisplayPath, saveCredentials } from '../config.js';
+const DEFAULT_APP_URL = process.env.NEWLY_APP_URL ?? 'https://newly.app';
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+export async function startCallbackServer(state, appOrigin, timeoutMs) {
+    let resolvePayload;
+    let rejectPayload;
+    const payloadPromise = new Promise((resolve, reject) => {
+        resolvePayload = resolve;
+        rejectPayload = reject;
+    });
+    const timer = setTimeout(() => rejectPayload(new Error(`Login timed out after ${timeoutMs / 1000}s`)), timeoutMs);
+    const corsHeaders = {
+        'Access-Control-Allow-Origin': appOrigin,
+        'Access-Control-Allow-Methods': 'POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'content-type',
+    };
+    const server = http.createServer((req, res) => {
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204, corsHeaders);
+            res.end();
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.writeHead(405, corsHeaders);
+            res.end();
+            return;
+        }
+        let body = '';
+        req.on('data', (chunk) => (body += chunk));
+        req.on('end', () => {
+            try {
+                const parsed = JSON.parse(body);
+                if (parsed.state !== state) {
+                    res.writeHead(403, corsHeaders);
+                    res.end('state mismatch');
+                    return;
+                }
+                res.writeHead(200, { ...corsHeaders, 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: true }));
+                clearTimeout(timer);
+                resolvePayload(parsed);
+            }
+            catch {
+                res.writeHead(400, corsHeaders);
+                res.end('bad request');
+            }
+        });
+    });
+    const port = await new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            resolve(typeof addr === 'object' && addr ? addr.port : 0);
+        });
+    });
+    return {
+        port,
+        waitForToken: () => payloadPromise,
+        close: () => {
+            clearTimeout(timer);
+            server.close();
+        },
+    };
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {
+    });
+    child.unref();
+}
+export function parseManualCredential(blob) {
+    let parsed;
+    try {
+        parsed = JSON.parse(blob);
+    }
+    catch {
+        throw new Error('Could not parse the pasted credential as JSON. Copy the entire blob shown in the browser and try again.');
+    }
+    const c = parsed;
+    if (typeof c.token !== 'string' || typeof c.expiresIn !== 'number' || typeof c.apiUrl !== 'string') {
+        throw new Error('Pasted credential is missing required fields (expected JSON with token, expiresIn, apiUrl). ' +
+            'Copy the entire blob shown in the browser.');
+    }
+    return { token: c.token, expiresIn: c.expiresIn, apiUrl: c.apiUrl };
+}
+export function registerLogin(program) {
+    program
+        .command('login')
+        .description('Log in with your Newly account via the browser')
+        .option('--app-url <url>', 'Newly web app URL', DEFAULT_APP_URL)
+        .option('--manual', 'paste the credential from the browser instead of using the local callback', false)
+        .option('--api-url <url>', 'explicit API URL (skips browser; use with --token)')
+        .option('--token <token>', 'explicit credential token (skips browser; use with --api-url)')
+        .option('--expires-in <seconds>', 'session lifetime when using --token (default 7 days)', (v) => Number(v), 604800)
+        .action(async (opts) => {
+        try {
+            const hasApiUrl = typeof opts.apiUrl === 'string' && opts.apiUrl.length > 0;
+            const hasToken = typeof opts.token === 'string' && opts.token.length > 0;
+            if (hasApiUrl !== hasToken) {
+                throw new Error('--api-url and --token must be provided together for headless login.');
+            }
+            if (hasApiUrl && hasToken) {
+                try {
+                    new URL(opts.apiUrl);
+                }
+                catch {
+                    throw new Error(`--api-url is not a valid URL: ${opts.apiUrl}`);
+                }
+                saveCredentials({
+                    token: opts.token,
+                    apiUrl: opts.apiUrl,
+                    appUrl: opts.appUrl,
+                    expiresAt: Math.floor(Date.now() / 1000) + opts.expiresIn,
+                });
+                console.log(`Logged in headlessly. Credentials written for API ${opts.apiUrl}.`);
+                return;
+            }
+            if (opts.manual) {
+                const { createInterface } = await import('node:readline/promises');
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                const blob = await rl.question('Paste the credential from the browser: ');
+                rl.close();
+                const parsed = parseManualCredential(blob);
+                saveCredentials({
+                    token: parsed.token,
+                    apiUrl: parsed.apiUrl,
+                    appUrl: opts.appUrl,
+                    expiresAt: Math.floor(Date.now() / 1000) + parsed.expiresIn,
+                });
+                console.log('Logged in.');
+                return;
+            }
+            const state = crypto.randomBytes(16).toString('hex');
+            const appOrigin = new URL(opts.appUrl).origin;
+            const { port, waitForToken, close } = await startCallbackServer(state, appOrigin, LOGIN_TIMEOUT_MS);
+            const loginUrl = `${opts.appUrl}/cli-auth?port=${port}&state=${state}`;
+            console.log(`Opening your browser to authorize the CLI…\n  ${loginUrl}\n`);
+            console.log("If the browser doesn't open, paste the URL above into it manually.");
+            openBrowser(loginUrl);
+            try {
+                const payload = await waitForToken();
+                saveCredentials({
+                    token: payload.token,
+                    apiUrl: payload.apiUrl,
+                    appUrl: opts.appUrl,
+                    expiresAt: Math.floor(Date.now() / 1000) + payload.expiresIn,
+                });
+                console.log(`Logged in. Credentials saved to ${credentialsDisplayPath()}`);
+            }
+            finally {
+                close();
+            }
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('logout')
+        .description('Delete the stored CLI credential')
+        .action(() => {
+        clearCredentials();
+        console.log('Logged out.');
+    });
+}

package/dist/commands/misc.js

@@ -0,0 +1,175 @@
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject } from '../config.js';
+export function assertDevOnly(env, command) {
+    if (env !== 'dev') {
+        throw new Error(`\`newly ${command}\` is dev-only from the CLI. Prod ${command} requires the Newly web app (a browser session).`);
+    }
+}
+export function parseDuration(s) {
+    const m = /^(\d+)(s|m|h)$/.exec(s.trim());
+    if (!m)
+        throw new Error(`Invalid duration "${s}" (use e.g. 30s, 5m, 2h)`);
+    const n = Number(m[1]);
+    const unit = m[2];
+    const mult = unit === 's' ? 1_000 : unit === 'm' ? 60_000 : 3_600_000;
+    return n * mult;
+}
+const ISO_8601 = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})?)?$/;
+function validateIso(s) {
+    if (!ISO_8601.test(s) || Number.isNaN(Date.parse(s))) {
+        throw new Error(`Invalid ISO 8601 timestamp "${s}" (expected e.g. 2026-06-15 or 2026-06-15T08:00:00Z)`);
+    }
+}
+export function resolveLogWindow(opts, now = Date.now()) {
+    let start = opts.start;
+    if (!start && opts.since)
+        start = new Date(now - parseDuration(opts.since)).toISOString();
+    if (opts.start)
+        validateIso(opts.start);
+    if (opts.end)
+        validateIso(opts.end);
+    return { start, end: opts.end };
+}
+export function formatLogEntry(e) {
+    if (!e || typeof e !== 'object')
+        return String(e);
+    const ts = e.ts ?? '-';
+    const sev = (e.severity ?? 'OK').padEnd(5);
+    const trace = e.trace_id ? ` trace=${e.trace_id.slice(0, 16)}` : '';
+    const name = e.name ?? '';
+    return `${ts} ${sev} ${name}${trace}`.trimEnd();
+}
+export async function fetchLogs(client, projectId, env, service, pageSize, bounds = {}, filters = {}) {
+    const params = new URLSearchParams();
+    params.set('env', env);
+    params.set('service', service);
+    params.set('page_size', String(pageSize));
+    if (bounds.start)
+        params.set('start', bounds.start);
+    if (bounds.end)
+        params.set('end', bounds.end);
+    if (filters.severityMin)
+        params.set('severity_min', filters.severityMin);
+    if (filters.traceId)
+        params.set('trace_id', filters.traceId);
+    if (filters.textSearch)
+        params.set('text_search', filters.textSearch);
+    const out = await client.get(`/newly_backend/logs/${encodeURIComponent(projectId)}?${params.toString()}`);
+    if (Array.isArray(out.entries)) {
+        return out.entries.map((e) => formatLogEntry(e)).join('\n');
+    }
+    if (typeof out.logs === 'string')
+        return out.logs;
+    if (Array.isArray(out.lines))
+        return out.lines.join('\n');
+    return JSON.stringify(out, null, 2);
+}
+export async function listSecrets(client, projectId, env, service) {
+    const out = await client.get(`/newly_backend/read_secrets?project_id=${encodeURIComponent(projectId)}&env=${env}&service=${service}`);
+    if (Array.isArray(out.keys))
+        return [...out.keys].sort().join('\n');
+    const secrets = out.secrets ?? out;
+    return Object.keys(secrets).sort().join('\n');
+}
+export async function setSecret(client, projectId, env, service, key, value) {
+    await client.post('/newly_backend/set_secret', {
+        project_id: projectId,
+        env,
+        service,
+        key,
+        value,
+    });
+}
+export async function getDbUrl(client, projectId, env) {
+    const out = await client.get(`/newly_backend/readonly_db_url?project_id=${encodeURIComponent(projectId)}&env=${env}`);
+    return out.database_url ?? out.url ?? JSON.stringify(out);
+}
+function makeClient(project) {
+    const creds = requireCredentials();
+    return {
+        client: new ApiClient(creds.apiUrl, creds.token),
+        projectId: resolveProject(process.cwd(), project),
+    };
+}
+export function registerMisc(program) {
+    program
+        .command('logs')
+        .description('Tail backend service logs')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--service <service>', 'api | auth', 'api')
+        .option('-n, --lines <n>', 'page size (number of log entries to fetch)', '200')
+        .option('--since <duration>', 'relative window, e.g. 5m, 1h, 30s')
+        .option('--start <iso>', 'window start (ISO 8601 timestamp)')
+        .option('--end <iso>', 'window end (ISO 8601 timestamp)')
+        .option('--severity <min>', 'min severity: ok | warn | error')
+        .option('--trace <id>', 'restrict to a single trace_id')
+        .option('--search <text>', 'substring filter on the entry name')
+        .option('--project <id>', 'project id')
+        .action(async (opts) => {
+        try {
+            assertDevOnly(opts.env, 'logs');
+            if (opts.service !== 'api' && opts.service !== 'auth') {
+                throw new Error(`--service must be 'api' or 'auth' (got ${JSON.stringify(opts.service)})`);
+            }
+            const bounds = resolveLogWindow(opts);
+            const { client, projectId } = makeClient(opts.project);
+            console.log(await fetchLogs(client, projectId, opts.env, opts.service, Number(opts.lines), bounds, { severityMin: opts.severity, traceId: opts.trace, textSearch: opts.search }));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+    const secrets = program.command('secrets').description('Manage backend secrets');
+    secrets
+        .command('list')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--service <service>', 'backend service name', 'worker')
+        .option('--project <id>', 'project id')
+        .action(async (opts) => {
+        try {
+            assertDevOnly(opts.env, 'secrets list');
+            const { client, projectId } = makeClient(opts.project);
+            console.log(await listSecrets(client, projectId, opts.env, opts.service));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+    secrets
+        .command('set')
+        .argument('<key>')
+        .argument('<value>')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--service <service>', 'backend service name', 'worker')
+        .option('--project <id>', 'project id')
+        .action(async (key, value, opts) => {
+        try {
+            assertDevOnly(opts.env, 'secrets set');
+            const { client, projectId } = makeClient(opts.project);
+            await setSecret(client, projectId, opts.env, opts.service, key, value);
+            console.log(`Secret ${key} set for ${opts.service} (${opts.env}). Redeploy to apply.`);
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+    const db = program.command('db').description('Database helpers');
+    db.command('url')
+        .description('Print a readonly URL for the Newly DB')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--project <id>', 'project id')
+        .action(async (opts) => {
+        try {
+            assertDevOnly(opts.env, 'db url');
+            const { client, projectId } = makeClient(opts.project);
+            console.log(await getDbUrl(client, projectId, opts.env));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/pull.js

@@ -0,0 +1,53 @@
+import { readdirSync } from 'node:fs';
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject, writeProjectLink } from '../config.js';
+import { extractSnapshot, pruneStaleTopLevel, snapshotTopLevelEntries } from '../archive.js';
+export function assertPullTarget(dir, force) {
+    const entries = readdirSync(dir).filter((e) => e !== '.newly');
+    if (entries.length > 0 && !force) {
+        throw new Error(`Target directory is not empty. Re-run with --force to overwrite local files (this discards local changes).`);
+    }
+}
+export async function extractTarball(data, dir) {
+    await extractSnapshot(data, dir);
+}
+export function registerPull(program) {
+    program
+        .command('pull')
+        .argument('[project-id]', 'Newly project id (defaults to the linked project in this directory)')
+        .description('Download the project working tree (app + backend) into the current directory')
+        .option('--force', 'overwrite files in a non-empty directory', false)
+        .option('--branch <name>', 'branch to pull (defaults to the project active branch / main)')
+        .action(async (projectIdArg, opts) => {
+        try {
+            const creds = requireCredentials();
+            const dir = process.cwd();
+            const projectId = resolveProject(dir, projectIdArg);
+            assertPullTarget(dir, opts.force);
+            const client = new ApiClient(creds.apiUrl, creds.token);
+            const query = opts.branch ? `?branch=${encodeURIComponent(opts.branch)}` : '';
+            console.log(`Downloading project ${projectId}${opts.branch ? ` (branch ${opts.branch})` : ''}…`);
+            const res = (await client.get(`/newly_backend/repo_archive/${projectId}${query}`));
+            const data = Buffer.from(await res.arrayBuffer());
+            if (opts.force) {
+                const keep = await snapshotTopLevelEntries(data);
+                const removed = pruneStaleTopLevel(dir, keep);
+                if (removed.length > 0) {
+                    console.log(`Removed ${removed.length} stale top-level ${removed.length === 1 ? 'entry' : 'entries'} not in the pulled tree: ${removed.join(', ')}`);
+                }
+            }
+            await extractTarball(data, dir);
+            const pulledBranch = res.headers.get('x-newly-branch');
+            writeProjectLink(dir, {
+                projectId,
+                pulledSha: res.headers.get('x-newly-head-sha'),
+                pulledAt: new Date().toISOString(),
+            });
+            console.log(`Pulled${pulledBranch ? ` branch ${pulledBranch}` : ''} into ${dir} and linked to project ${projectId}.`);
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/run-cloud.js

@@ -0,0 +1,272 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials } from '../config.js';
+const RUN_CLOUD_SKILL = `---
+name: run-cloud-ios-simulator
+description: Build, install, and inspect iOS apps with run.cloud remote simulator sessions.
+version: 0.1.0
+---
+
+# run.cloud iOS Simulator
+
+Use this skill when a user asks an agent to run, inspect, smoke test, or debug an iOS app in a remote simulator through run.cloud.
+
+## Requirements
+
+- The user must be authenticated with \`runcloud login\`.
+- The account must have run.cloud access and a positive run.cloud balance.
+- App artifacts should be simulator-compatible builds. Device App Store IPAs may fail to install on iOS Simulator.
+
+## Workflow
+
+1. Check access with \`runcloud account --json\`.
+2. Create a simulator with \`runcloud ios create --install ./build/MyApp.tar.gz --json\`.
+3. Save the returned session id and URL.
+4. Use \`runcloud ios open-url <url> --id <session-id>\` when a URL or deep link must be opened.
+5. Release the session with \`runcloud ios delete <session-id>\`.
+
+## Embedded Iframes
+
+- Use \`runcloud ios create --inactivity-timeout 60s --json\` when the embed should auto-close after user inactivity.
+- Omit \`--inactivity-timeout\` or pass \`none\` when the user needs a metered session without idle auto-close.
+- Iframes post \`ios-simulator:status\`, \`ios-simulator:auth-error\`, \`ios-simulator:session-ended\`, and \`ios-simulator:session-restart-requested\` to the parent window. Verify \`event.source\` before acting.
+- If \`ios-simulator:session-restart-requested\` arrives, create a fresh run.cloud session; do not reuse the ended iframe URL.
+
+## Rules
+
+- Prefer \`--json\` for parsed output.
+- Always release sessions you create unless the user asks to keep them open.
+- If installation fails, verify that the artifact is a simulator build before attempting code changes.
+- Do not assume a local tunnel is installed on the user's machine.
+- Do not expose iOS simulator tokens in logs or screenshots.
+`;
+function client() {
+    const creds = requireCredentials();
+    return new ApiClient(creds.apiUrl, creds.token);
+}
+function print(value, opts = {}) {
+    if (opts.json) {
+        console.log(JSON.stringify(value, null, 2));
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            console.log(formatRecord(item));
+        return;
+    }
+    console.log(formatRecord(value));
+}
+function formatRecord(value) {
+    if (!value || typeof value !== 'object')
+        return String(value);
+    const record = value;
+    return Object.entries(record)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => `${k}: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`)
+        .join('\n');
+}
+function parseLabels(labels) {
+    const out = {};
+    for (const raw of labels ?? []) {
+        const idx = raw.indexOf('=');
+        if (idx <= 0)
+            throw new Error(`Invalid --label ${raw}; expected key=value`);
+        out[raw.slice(0, idx)] = raw.slice(idx + 1);
+    }
+    return out;
+}
+function fileBlob(path) {
+    const resolved = resolve(path);
+    if (!existsSync(resolved))
+        throw new Error(`File does not exist: ${path}`);
+    if (!statSync(resolved).isFile())
+        throw new Error(`Not a file: ${path}`);
+    const data = readFileSync(resolved);
+    return {
+        blob: new Blob([new Uint8Array(data)], { type: 'application/octet-stream' }),
+        name: basename(resolved),
+    };
+}
+function skillBase(agent, scope) {
+    if (scope === 'project') {
+        if (agent === 'claude')
+            return join(process.cwd(), '.claude', 'skills');
+        if (agent === 'codex')
+            return join(process.cwd(), '.codex', 'skills');
+        if (agent === 'cursor')
+            return join(process.cwd(), '.agents', 'skills');
+    }
+    if (agent === 'claude')
+        return join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), 'skills');
+    if (agent === 'codex')
+        return join(process.env.CODEX_HOME ?? join(homedir(), '.codex'), 'skills');
+    if (agent === 'cursor')
+        return join(homedir(), '.agents', 'skills');
+    throw new Error(`Unsupported agent: ${agent}`);
+}
+function installSkill(opts) {
+    const agents = opts.agents?.length ? opts.agents : ['claude', 'codex', 'cursor'];
+    const scope = opts.scope ?? 'project';
+    const results = [];
+    for (const agent of agents) {
+        const target = join(skillBase(agent, scope), 'run-cloud-ios-simulator');
+        if (existsSync(target)) {
+            if (!opts.force)
+                throw new Error(`${target} already exists. Pass --force to overwrite.`);
+            rmSync(target, { recursive: true, force: true });
+        }
+        mkdirSync(target, { recursive: true });
+        writeFileSync(join(target, 'SKILL.md'), RUN_CLOUD_SKILL);
+        results.push({ agent, path: target, status: 'installed' });
+    }
+    return results;
+}
+async function pushAsset(path, opts = {}) {
+    const { blob, name } = fileBlob(path);
+    const form = new FormData();
+    form.set('file', blob, name);
+    if (opts.name)
+        form.set('name', opts.name);
+    return (await client().uploadForm('/run-cloud/assets', form));
+}
+async function action(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        console.error(friendlyApiError(err));
+        process.exitCode = 1;
+    }
+}
+export function registerRunCloud(program) {
+    program
+        .command('account')
+        .description('Show run.cloud entitlement and metered balance')
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        print(await client().get('/run-cloud/account'), opts);
+    }));
+    const ios = program.command('ios').description('Create, list, inspect, and delete iOS simulator sessions');
+    ios
+        .command('create')
+        .description('Create a remote iOS simulator session')
+        .option('--model <iphone|ipad>', 'simulator model', 'iphone')
+        .option('--region <region>', 'fleet region')
+        .option('--display-name <name>', 'human-readable name')
+        .option('--label <key=value>', 'label to attach to the session', (v, p) => [...p, v], [])
+        .option('--install <file>', 'local .ipa, .zip, .tar.gz, or simulator .app archive to upload and install', (v, p) => [...p, v], [])
+        .option('--install-asset <name-or-id>', 'previously uploaded asset to install', (v, p) => [...p, v], [])
+        .option('--inactivity-timeout <duration>', 'auto-close idle timeout, e.g. 60s, 3m, or none')
+        .option('--hard-timeout <duration>', 'maximum lifetime, e.g. 10m or 1h')
+        .option('--rm', 'release the session when this command exits', false)
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        const uploadedAssets = [];
+        for (const file of opts.install ?? [])
+            uploadedAssets.push(await pushAsset(file));
+        const installAssets = [
+            ...(opts.installAsset ?? []),
+            ...uploadedAssets
+                .map((asset) => asset.id)
+                .filter((id) => typeof id === 'string' && id.length > 0),
+        ];
+        const session = await client().post('/run-cloud/ios', {
+            model: opts.model,
+            region: opts.region,
+            displayName: opts.displayName,
+            labels: parseLabels(opts.label),
+            installAssets,
+            inactivityTimeout: opts.inactivityTimeout,
+            hardTimeout: opts.hardTimeout,
+            autoDelete: opts.rm,
+        });
+        print(session, opts);
+    }));
+    ios
+        .command('list')
+        .description('List active iOS simulator sessions')
+        .option('--all', 'include released sessions', false)
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        const qs = opts.all ? '?all=1' : '';
+        print(await client().get(`/run-cloud/ios${qs}`), opts);
+    }));
+    ios
+        .command('get')
+        .description('Show an iOS simulator session')
+        .argument('<id>')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        print(await client().get(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+    }));
+    ios
+        .command('delete')
+        .description('Release an iOS simulator session')
+        .argument('<id>')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        print(await client().delete(`/run-cloud/ios/${encodeURIComponent(id)}`), opts);
+    }));
+    ios
+        .command('open-url')
+        .description('Open a URL or deep link in an iOS simulator session')
+        .argument('<url>')
+        .requiredOption('--id <id>', 'session id')
+        .option('--json', 'output JSON', false)
+        .action((url, opts) => action(async () => {
+        print(await client().post(`/run-cloud/ios/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
+    }));
+    const asset = program
+        .command('asset')
+        .alias('assets')
+        .description('Upload, list, inspect, and delete run.cloud assets');
+    asset
+        .command('push')
+        .description('Upload an app asset for simulator installation')
+        .argument('<file>')
+        .option('-n, --name <name>', 'asset name')
+        .option('--json', 'output JSON', false)
+        .action((file, opts) => action(async () => {
+        print(await pushAsset(file, opts), opts);
+    }));
+    asset
+        .command('list')
+        .description('List uploaded assets')
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        print(await client().get('/run-cloud/assets'), opts);
+    }));
+    asset
+        .command('pull')
+        .description('Download an asset')
+        .argument('<id>')
+        .option('-o, --output <path>', 'output path')
+        .action((id, opts) => action(async () => {
+        const body = await client().getBinary(`/run-cloud/assets/${encodeURIComponent(id)}/download`);
+        const output = opts.output ?? id;
+        writeFileSync(output, body);
+        console.log(output);
+    }));
+    asset
+        .command('delete')
+        .description('Delete an uploaded asset')
+        .argument('<id>')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        print(await client().delete(`/run-cloud/assets/${encodeURIComponent(id)}`), opts);
+    }));
+    const skills = program.command('skills').description('Install run.cloud skills for AI coding agents');
+    skills
+        .command('install')
+        .description('Install the run.cloud iOS simulator skill')
+        .option('--agents <agent>', 'agent to install for: claude, codex, cursor', (v, p) => [...p, v], [])
+        .option('--scope <project|global>', 'install scope', 'project')
+        .option('--force', 'overwrite existing skill', false)
+        .option('--json', 'output JSON', false)
+        .action((opts) => action(async () => {
+        const scope = opts.scope === 'global' ? 'global' : 'project';
+        print(installSkill({ ...opts, scope }), opts);
+    }));
+}