Skip to content
LogoLogo

How to switch workspaces

This guide shows you how to point your local tooling at a different project or workspace. Your application then renders that workspace's content and types on your machine. It expects a picked.config.ts and the CLI.

Your tooling reads the project and surface named in the committed picked.config.ts. The CLI writes your choice to .picked/settings.json instead. That file is per-developer and Git ignores it, so the committed default stays as it is and one command puts it back.

See Workspaces for what Live, Draft, and Archived mean.

1. Sign in

picked login

This opens your browser for a one-time OAuth sign-in and stores a session under ~/.picked/. Confirm it with picked whoami. See CLI authentication.

2. Find a workspace

picked workspace list
Acme Corp. (acme-corporation)
  Storefront [proj_a1b2]
    Default Storefront [LIVE] (live)
    Checkout rework [DRAFT]

Note the project id (proj_a1b2) and the name or the id of the workspace you want.

3. Switch to the draft

picked workspace use --project proj_a1b2 --workspace ws_draft
Active workspace: Checkout rework [DRAFT] in project proj_a1b2 (source: preview)
Generated types at /app/src/picked-env.d.ts

A command that names one specific workspace (draft, live, or archived):

  • writes the selection (and its preview token) to .picked/settings.json,
  • switches the resolved source to preview for that project, and
  • regenerates picked-env.d.ts from that workspace's schema (skip with --no-generate).

To browse instead, run picked workspace use with no flags. The interactive picker lists every project, with Published (live version) and each of its workspaces.

4. See the draft in your app

Both readers of the selection use .picked/settings.json with no change to your configuration:

  • Type generation now reads the draft schema. Rerun picked generate types after more edits.
  • The Vite plugin reads the draft's configuration and content in development and in a build. It sends the preview token to the Delivery API. Restart the dev server to apply a switch.

Your application renders the unpublished draft on your machine, with types.

5. Switch back to live

picked workspace use --project proj_a1b2

A command that names a project with no --workspace, or Published (live version) in the picker, discards the preview token and returns source to published. To confirm what is active:

picked status
Config default: project proj_a1b2 (source: published)
Active selection: none (using the config default).

CI and headless runs

.picked/settings.json is a local, per-developer file. Do not commit it. To choose one workspace in CI with no selection file, set the environment directly:

PICKED_PROJECT_ID=proj_a1b2 \
PICKED_PREVIEW_TOKEN="$DRAFT_TOKEN" \
  picked generate types --check

PICKED_PREVIEW_TOKEN applies only when the resolved source is preview. See the CLI environment variables for the full precedence order.