Workspace, Operator, and roadmap commands
Check out draft variation workspaces, run live previews, publish workspace files, and pull approved roadmap handoffs.
Use apex workspace for variation-level draft workspace files used by Apex Operator and code workbench flows. The command group also has the operator alias.
Check out a workspace
apex workspace checkout 00000000-0000-4000-8000-000000000001 \
--variation variant-a \
--dir ./homepage-hero| Command | Arguments | Flags | Behavior |
|---|---|---|---|
apex workspace checkout | <experiment-id> | --variation <id-or-slug>, --dir <folder> | Pulls one variation workspace and writes .apex/session.json. |
apex workspace status | [folder] | None beyond global flags | Shows local files, hashes, sizes, and changed paths. |
apex workspace dev | [folder] | --no-open, --once | Creates an exact harness session, uploads the current preview artifact, opens or prints the preview URL, and watches files unless --once is used. |
apex workspace publish | [folder] | None beyond global flags | Uploads changed files, builds the workspace through Apex, refreshes local session metadata, and publishes external artifacts when configured. |
Supported workspace files
src/index.js
src/index.scss
src/info.js
src/mutations.json
experiment.config.json
metrics.json
targeting.json
dev-doc.md
brand.md
goals/<name>.json
segments/<name>.json
network/<name>.recipe.jsonbrand.md is generated read-only context. Local edits to brand.md are ignored during publish.
Preview workflow
apex workspace status ./homepage-hero --json
apex workspace dev ./homepage-hero --no-open
apex workspace dev ./homepage-hero --oncedev reads the local session, creates a harness session for the exact experiment and variation, uploads the current src/index.js and optional src/index.scss, then writes .apex/harness-session.json with the preview metadata. Without --once, it watches the workspace and uploads new preview versions after local file changes.
Preview URLs include short-lived harness tokens. Treat them like secrets.
Publish workflow
apex workspace publish ./homepage-heroPublish validates JSON files, uploads changed supported files except brand.md, asks Apex to build the workspace, and refreshes local session metadata from the server. When experiment.config.json opts into external delivery with externalCode, deliveryMode: "external", or codeDeliveryMode: "external", publish also creates a harness session, uploads the current artifact, and publishes that harness session.
Publishing syncs draft artifacts back to Apex. It does not launch public traffic.
Roadmap handoffs
Use roadmap commands when your API key can access approved ideas and you need a build brief.
apex roadmap approved --unbuilt --brief
apex roadmap approved --query "homepage" --limit 10
apex roadmap handoff 00000000-0000-4000-8000-000000000002 --instructions
apex roadmap handoff 00000000-0000-4000-8000-000000000002 --output ./handoff.json| Command | Flags | Behavior |
|---|---|---|
apex roadmap approved | --limit <n>, --cursor <id>, --query <text>, --unbuilt, --built, --brief, --json | Lists approved roadmap ideas, optionally filtered to linked or unlinked experiments. |
apex roadmap handoff | --output <path>, --instructions | Reads the full build handoff for one approved item, or just the instructions text. |