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 \
--out ./homepage-hero| Command | Arguments | Flags | Behavior |
|---|---|---|---|
apex workspace checkout | <experiment-id> | --variation <id-or-slug>, --out <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.
Dev never changes the experiment's name, store URL, reset script or anti-flicker selectors. The preview opens on experiment.config.json storeUrl (or the experiment's store URL). When Apex refuses the session, nothing is created and the error lists each blocking issue with its code (error.code harness_artifacts_blocked).
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 --out ./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 | --out <path>, --instructions | Reads the full build handoff for one approved item, or just the instructions text. |
Related pages
- Experiment filesystem and QA commands
- Preview and harness commands
- Agent tools: SOS, brand, schema, and skills
Export contract
--instructions cannot be combined with --out (or its legacy alias --output); file exports always contain the full JSON contract.
apex roadmap handoff <id> --json returns apex.roadmap_handoff.v1 in the CLI
wrapper's data. --out writes that exact contract object. apex backlog get
and apex backlog list identify each item as apex.backlog_item.v1.
Both have schema_version: 1. The backlog version is an independent concurrency
token, not a schema version.
There is one item contract: the handoff embeds the closed item shape under item;
backlog get/list expose the same fields alongside the existing raw row fields.
Select the contract properties from a raw row before validating the closed schema.
Every key below is required. Unknown optional values are explicit null; acceptance
criteria are an empty array unless metadata contains an array consisting only of strings.
| Key | Type | Nullable | Source |
|---|---|---|---|
contract, schema_version | string, integer | No | Contract id, literal 1 |
id, title, status, stage | string | No | Backlog row; stage is the approval lifecycle |
ticket_key | string | Yes | metadata.backlog_key |
hypothesis, device | string | Yes | Backlog row |
approval | object | No | Roadmap decision status (proposed without a decision), item stage, and decision's nullable decided_at |
page | object | No | Nullable label, url, type; row page fields and known page vocabulary |
research_hub | object | No | Nullable brand_id, idea_id from row; company_id is currently null |
acceptance_criteria | string array | No | metadata.acceptance_criteria, otherwise [] |
mockups | object | No | precedence: "primary_first", nullable primary, array others; active visual refs in order |
main_metric_goal_id | string | Yes | Backlog row |
created_at, updated_at | string | No | Row timestamps serialized as ISO dates |
The handoff additionally guarantees:
| Key | Type | Nullable | Source |
|---|---|---|---|
item | object | No | Shared item projection above, without its standalone discriminator |
experiment | object | Yes | Linked experiment: id, test_key, slug, name, status, variation_id, variation_slug, variation_name, target_url (each nullable) |
instructions | string | No | Build brief |
goals | object array | No | Handoff metrics: name, role (primary/secondary), nullable apex_goal_id and event; apex_goal_id is the linked experiment goal or null |
mockups | object | No | Handoff visuals, including linked experiment references after backlog references |
acceptance_criteria | string array | No | Same as item.acceptance_criteria |
harness, scoring | object | No | Existing handoff metadata blocks |
source | string | No | Existing handoff source |
metadata | object | No | Existing block retained, including schemaVersion: 1 |
Visual refs carry nullable url, storagePath, label, description, kind, and
non-null source. The primary ref takes precedence over every entry in others.
Missing goal ids or events stay null; built-in metric names do not invent stored goals.
A removal, rename, semantic change, or nullable-field change requires a new .v2.
schema and contract id. Pin the version you consume.