@xyz/studio

The studio CLI and the createStudio() library API: capture a website, redesign it with your prompts through Claude Code, screenshot, publish and email the result.

Quick start

Needs Node 20+ and Claude Code installed and logged in.

npx @xyz/studio init my-client --name "My Client" --url https://example.com --email-provider stub
cd my-client
npx @xyz/studio doctor --fix          # checks the setup and installs the chromium build studio needs
npx @xyz/studio redesign create https://example.com "Give this page a modern refresh" --workflow quick
npx @xyz/studio runs open <run-id>    # view the result
npx @xyz/studio dashboard --root ~/Clients   # or do all of this in the local dashboard (browser, 127.0.0.1 only)

Or install it once: npm install -g @xyz/studio, then run studio ….

The configuration guide (prompts, skills, steps, pages, variants, models, the dashboard) ships in this package as dist/guide.md. The rest of this file is the command reference.

Every command accepts the global options below. With --json, a command prints exactly one envelope on stdout, { ok, command, data, warnings, error? }, and sends its logs to stderr. Exit codes: 0 ok (a partial run included), 1 failed, 2 usage error, 3 blocked (engine missing or logged out, preview service unreachable, capture blocked by the site).

The sections below are the commands' own --help output. Regenerate them after changing a command: build, then run each studio <command> --help.

Library

import { createStudio } from '@xyz/studio'

const studio = createStudio({ workspaceDir: '/path/to/workspace' })
const outcome = await studio.design('Landing page for a Bahrain coffee roaster', { variants: 3 })
console.log(outcome.status, outcome.record.variants)

createStudio exposes run, design, redesign, resume, runs, skills, workflows, capture, screenshot and offer. A non-zero exit code comes back in the outcome instead of being thrown.

studio

Usage: studio [options] [command]

XYZ Studio: design and redesign websites through AI coding CLIs

Options:
  -V, --version                    print the studio version
  --json                           print a JSON envelope on stdout; logs go to
                                   stderr (default: false)
  --workspace <dir>                workspace directory (default: nearest parent
                                   with .xyz/)
  --verbose                        verbose logging on stderr (default: false)
  --no-color                       disable colored output
  --yes                            answer yes to confirmations (default: false)
  --force                          overwrite existing files and redo completed
                                   work (default: false)
  -h, --help                       display help for command

Commands:
  init [options] [dir]             create a client workspace (.xyz/,
                                   prospects.json, runs/, outbox/, captures/)
  doctor [options]                 check node, pnpm, the workspace, the engine,
                                   chromium, the preview service, email, skills
                                   and workflows
  skills                           list, inspect and copy skill packs
  workflows                        list, inspect and validate workflows
  capture [options] <url>          capture a live page: inert HTML, text,
                                   structure, images and before screenshots
  screenshot [options] <runId>     capture desktop (and optionally mobile)
                                   screenshots of every variant of a run
  run [options] <workflow>         run a workflow; --step/--from rerun steps of
                                   an existing run
  design                           brief-driven design runs
  redesign                         redesigns of an existing website
  runs                             list, inspect, open and resume runs
  publish [options] <runId>        upload a run’s variants to the preview
                                   service and save the receipt to publish.json
  stats [options] <runIdOrSiteId>  opens, views and clicks for a published run
                                   or site
  offer                            offer pipeline: import prospects, prepare,
                                   review and send offer emails, track them
  dashboard [options]              serve the local dashboard on 127.0.0.1
                                   (clients, workflows, runs); Ctrl-C to stop
  help [command]                   display help for command

studio init

Usage: studio init [options] [dir]

create a client workspace (.xyz/, prospects.json, runs/, outbox/, captures/)

Options:
  --name <name>                workspace and client name (default: the directory
                               name)
  --url <url>                  client website URL
  --email-provider <provider>  resend, smtp or stub (default: "stub")
  --preview-url <url>          preview service URL
  -h, --help                   display help for command

studio doctor

Usage: studio doctor [options]

check node, pnpm, the workspace, the engine, chromium, the preview service,
email, skills and workflows

Options:
  --live      also run the engine once ("Reply with OK", --max-budget-usd 0.05)
              (default: false)
  --fix       repair what can be repaired automatically (installs Playwright
              chromium) (default: false)
  -h, --help  display help for command

studio skills list

Usage: studio skills list [options]

global and workspace skills, with the workflows that use them

Options:
  -h, --help  display help for command

studio skills show

Usage: studio skills show [options] <name>

print a skill: source, digest, files and SKILL.md

Options:
  -h, --help  display help for command

studio skills add

Usage: studio skills add [options] <source>

copy a global skill, a local directory or a git repository into .xyz/skills/

Options:
  --as <name>      install under a different name
  --subdir <path>  directory inside the git repository that holds the skill
  -h, --help       display help for command

studio workflows list

Usage: studio workflows list [options]

list global and workspace workflows

Options:
  -h, --help  display help for command

studio workflows show

Usage: studio workflows show [options] <name>

print a workflow, where it was resolved from, and any graph problems

Options:
  -h, --help  display help for command

studio workflows validate

Usage: studio workflows validate [options] <name>

check a workflow against the schema and graph rules; exit 1 when it has problems

Options:
  -h, --help  display help for command

studio capture

Usage: studio capture [options] <url>

capture a live page: inert HTML, text, structure, images and before screenshots

Arguments:
  url                   page to capture (https:// is assumed when no scheme is
                        given)

Options:
  --out <dir>           output directory (default:
                        captures/<host>-<yyyymmdd-hhmm>/)
  --viewport <WxH>      viewport size (default: "1280x800")
  --timeout <ms>        navigation timeout in milliseconds (default: "45000")
  --max-assets <n>      maximum number of images to download (default: "50")
  --no-dismiss-banners  do not try to close cookie/consent banners
  --no-crawl            capture this page only (no site map crawl)
  --max-pages <n>       pages to capture including the home page (1–50; default:
                        capture.crawl.maxPages or 12)
  --max-depth <n>       link hops from the home page (1–5; default:
                        capture.crawl.maxDepth or 2)
  --include <glob>      only crawl URL paths matching this glob, e.g. /blog/**
                        (repeatable) (default: [])
  --exclude <glob>      never crawl URL paths matching this glob (repeatable)
                        (default: [])
  -h, --help            display help for command

studio run

Usage: studio run [options] <workflow>

run a workflow; --step/--from rerun steps of an existing run

Arguments:
  workflow             workflow name (.xyz/workflows/ first, then global) or
                       path to a workflow file

Options:
  --input <key=value>  workflow input (repeatable) (default: [])
  --set <path=value>   one-off workflow override, e.g.
                       steps.build.with.model=opus (repeatable) (default: [])
  --run <id>           existing run to operate on with --step/--from (default:
                       the latest run of this workflow)
  --step <id>          rerun only this step of an existing run
  --from <id>          rerun this step and every later step of an existing run,
                       reusing earlier outputs
  --dry-run            write steps/*/prompt.md without calling any engine
                       (default: false)
  --strict             fail the run when an onFail loop runs out of attempts
                       (default: false)
  --require-all        exit 1 when the run is partial (default: false)
  -h, --help           display help for command

studio design create

Usage: studio design create [options] <brief>

design new variants from a brief (sugar over `studio run design --input
brief=…`)

Arguments:
  brief                   what to design: business, audience, goals, must-haves

Options:
  --variants <n>          number of variants (workflow input `variants`)
  --pages <pages>         pages per variant (workflow input `pages`): redesign,
                          the most pages including home (default 5); design,
                          page names such as home,menu,contact
  --model <model>         engine model for every agent step
  --skill <name>          extra skill for every agent step (repeatable)
                          (default: [])
  --workflow <name>       workflow to run instead of the workspace default
  --no-screenshot         skip the screenshot step
  --publish               publish the variants to the preview service at the end
                          (default: false)
  --max-budget-usd <usd>  engine budget cap for every agent step
  --timeout <duration>    engine timeout for every agent step (ms, or 90s / 25m
                          / 1h)
  --require-all           exit 1 when the run is partial (default: false)
  --strict                fail the run when an onFail loop runs out of attempts
                          (default: false)
  --dry-run               write steps/*/prompt.md without calling any engine
                          (default: false)
  --capture <dir>         reuse an existing capture bundle instead of capturing
                          the site
  --prospect <id>         prospect from prospects.json: fills the url and
                          records the run on the prospect
  --compile-css           compile Tailwind into each variant's
                          assets/tailwind.css (replaces the CDN script; needs
                          @tailwindcss/cli or pnpm dlx) (default: false)
  -h, --help              display help for command

studio redesign create

Usage: studio redesign create [options] [url] [brief]

capture a site and design redesign variants (sugar over `studio run redesign
--input url=…`)

Arguments:
  url                     the site to redesign (optional with --prospect)
  brief                   extra direction for the redesign

Options:
  --variants <n>          number of variants (workflow input `variants`)
  --pages <pages>         pages per variant (workflow input `pages`): redesign,
                          the most pages including home (default 5); design,
                          page names such as home,menu,contact
  --model <model>         engine model for every agent step
  --skill <name>          extra skill for every agent step (repeatable)
                          (default: [])
  --workflow <name>       workflow to run instead of the workspace default
  --no-screenshot         skip the screenshot step
  --publish               publish the variants to the preview service at the end
                          (default: false)
  --max-budget-usd <usd>  engine budget cap for every agent step
  --timeout <duration>    engine timeout for every agent step (ms, or 90s / 25m
                          / 1h)
  --require-all           exit 1 when the run is partial (default: false)
  --strict                fail the run when an onFail loop runs out of attempts
                          (default: false)
  --dry-run               write steps/*/prompt.md without calling any engine
                          (default: false)
  --capture <dir>         reuse an existing capture bundle instead of capturing
                          the site
  --prospect <id>         prospect from prospects.json: fills the url and
                          records the run on the prospect
  --compile-css           compile Tailwind into each variant's
                          assets/tailwind.css (replaces the CDN script; needs
                          @tailwindcss/cli or pnpm dlx) (default: false)
  --no-crawl              capture the start page only (no site crawl)
  --max-pages <n>         pages to capture including the home page (1–50)
  --max-depth <n>         link hops from the home page (1–5)
  --include <glob>        only crawl URL paths matching this glob, e.g. /blog/**
                          (repeatable) (default: [])
  --exclude <glob>        never crawl URL paths matching this glob (repeatable)
                          (default: [])
  -h, --help              display help for command

studio runs list

Usage: studio runs list [options]

runs in this workspace, newest first

Options:
  -h, --help  display help for command

studio runs show

Usage: studio runs show [options] <id>

print a run: steps, engine sessions and costs, variants

Arguments:
  id          run id (or path to a run dir)

Options:
  -h, --help  display help for command

studio runs open

Usage: studio runs open [options] <id>

serve the run's variants on 127.0.0.1 and print the URL of each variant and its
pages (Ctrl-C to stop)

Arguments:
  id                run id (or path to a run dir)

Options:
  --variant <slug>  only this variant
  --port <port>     port to listen on (default: a free port)
  --no-browser      do not open a browser window
  -h, --help        display help for command

studio runs resume

Usage: studio runs resume [options] <id>

continue a run from its first step that is not done

Arguments:
  id                  run id (or path to a run dir)

Options:
  --from <id>         rerun this step and every later step
  --step <id>         rerun only this step
  --set <path=value>  workflow override applied to this run (repeatable)
                      (default: [])
  --dry-run           write steps/*/prompt.md without calling any engine
                      (default: false)
  --strict            fail the run when an onFail loop runs out of attempts
                      (default: false)
  --require-all       exit 1 when the run is partial (default: false)
  -h, --help          display help for command

studio screenshot

Usage: studio screenshot [options] <runId>

capture desktop (and optionally mobile) screenshots of every variant of a run

Arguments:
  runId             run id under runs/, or a path to a run directory

Options:
  --width <px>      desktop viewport width (default 1280) (default: 1280)
  --mobile          also capture a 390x844 mobile screenshot (default: false)
  --slug <slug...>  only these variants (default: all)
  -h, --help        display help for command

Use the global --force to re-capture variants whose index.html is unchanged.

studio publish

Usage: studio publish [options] <runId>

upload a run’s variants to the preview service and save the receipt to
publish.json

Arguments:
  runId               run id under runs/

Options:
  --variants <slugs>  comma-separated variant slugs (default: every verified
                      variant)
  --site-id <id>      publish under this site id instead of <ws8>-<runId>
  --url <url>         preview service URL (default: preview.url in
                      .xyz/config.json)
  -h, --help          display help for command

Global --force: re-upload even when the service already holds this bundle, AND allow a
republish that drops previously published variants (the service deletes them with their
tracked links and stats). Unverified variants are published only when named in --variants.

studio stats

Usage: studio stats [options] <runIdOrSiteId>

opens, views and clicks for a published run or site

Arguments:
  runIdOrSiteId         a published run id, or a site id (<ws8>-<runId>)

Options:
  --since <when>        only count events since a duration ago (7d, 12h, 30m,
                        2w) or an ISO date
  --by <breakdown>      table to print: variant or prospect (default: "variant")
  --watch               refresh until interrupted with Ctrl-C (--json prints one
                        envelope per refresh) (default: false)
  --interval <seconds>  refresh interval for --watch (default 10) (default: 10)
  --url <url>           preview service URL (default: preview.url in
                        .xyz/config.json)
  -h, --help            display help for command

studio offer import

Usage: studio offer import [options] <file>

upsert prospects from a JSON or CSV file into prospects.json (by email)

Arguments:
  file               prospects file (.json array or .csv with a header row)

Options:
  --format <format>  json or csv (default: from the extension)
  --replace          replace stored fields of matching prospects and drop
                     prospects absent from the file (unsubscribed ones are kept)
  -h, --help         display help for command

studio offer prepare

Usage: studio offer prepare [options]

render one offer email per prospect into outbox/<campaign>/ (state prepared)

Options:
  --run <id>       offer this run to every selected prospect (default: each
                   prospect's own runId)
  --campaign <id>  campaign id (default: the run id)
  --prospect <id>  only this prospect (repeatable)
  --ai-copy        write the copy with the offer-copy workflow (default when
                   email.copy is "agent")
  --notes <text>   campaign notes passed to the offer-copy workflow
  --url <url>      preview service URL (default: preview.url in
                   .xyz/config.json)
  -h, --help       display help for command

Global --force re-renders items that already exist (never ones that are sending, sent or unknown).
The run must already be published (`studio publish <runId>`), with screenshots.

studio offer review

Usage: studio offer review [options]

list the outbox, approve or skip items, or open the local review page

Options:
  --campaign <id>  only this campaign
  --state <state>  only items in this state
  --open           serve the review page on 127.0.0.1:3344 until Ctrl-C
  --port <port>    review page port (default 3344; 0 picks a free one)
  --no-browser     with --open: do not open a browser window
  --approve-all    approve every prepared item
  --approve <id>   approve an item: prospect id or <campaign>/<prospectId>
                   (repeatable)
  --skip <id>      skip an item: prospect id or <campaign>/<prospectId>
                   (repeatable)
  -h, --help       display help for command

studio offer send

Usage: studio offer send [options]

send approved offer emails through the configured provider

Options:
  --campaign <id>       only this campaign
  --prospect <id>       only this prospect (repeatable)
  --dry-run             list what would be sent; send and write nothing
  --limit <n>           send at most n emails
  --retry-failed        also send items whose last attempt definitely failed
  --resend-unknown      also send items whose outcome is unknown (they may
                        already have been delivered)
  --include-unapproved  also send prepared items nobody approved (requires
                        --yes)
  --throttle <ms>       pause between sends (default email.throttleMs)
  -h, --help            display help for command

studio offer status

Usage: studio offer status [options]

the outbox by campaign; --with-stats joins opens/views/clicks from the preview
service

Options:
  --campaign <id>  only this campaign
  --with-stats     fetch stats from the preview service and join them per
                   prospect
  --url <url>      preview service URL (default: preview.url in
                   .xyz/config.json)
  -h, --help       display help for command

studio dashboard

Usage: studio dashboard [options]

serve the local dashboard on 127.0.0.1 (clients, workflows, runs); Ctrl-C to
stop

Options:
  --root <dir>   clients folder (remembered for next time; the page asks when
                 unset)
  --port <port>  port to listen on (default: a free port)
  --no-browser   do not open a browser window
  -h, --help     display help for command