Pairit CLI

A lightweight command line utility for working with Pairit experiment configuration files and media assets. It exposes grouped commands:

• login — authenticate with Google OAuth (required for all hosted commands)
• config lint — run minimal validation (schema_version, initialPageId, pages)
• config compile — normalize a YAML config and emit sibling canonical JSON
• config upload — compile and upload a config through the manager service, optionally with per-experiment LLM provider keys
• config list — list configs stored via the manager service
• config delete — delete a stored config
• media upload — upload a binary asset to Cloud Storage via the manager service (uploads are public unless --private is passed; the backend selects the bucket unless you override with --bucket)
• media list — list media objects in Cloud Storage
• media delete — delete a media object from Cloud Storage
• data export — export sessions, events, and chat messages for a config as CSV/JSON/JSONL

Install

bun install

You can invoke the CLI directly using Bun:

bun run src/index.ts --help

Link globally (optional)

cd apps/manager/cli
bun link

This makes pairit available globally from the bin field in package.json.

Usage

pairit login                                       # Authenticate (required first)
# On a remote/headless server, open the printed URL locally and paste back the one-time code

pairit config lint path/to/config.yaml
pairit config compile path/to/config.yaml
pairit config upload configs/simple-survey-basic.yaml --config-id simple-survey-basic
pairit config upload configs/agent-study.yaml --config-id agent-study --openai-api-key sk-...
pairit config list
pairit config delete 2f3c4d5e...

pairit media upload assets/video.mp4 --content-type video/mp4
pairit media list --prefix onboarding/
pairit media delete onboarding/intro.mp4

pairit data export <configId>                      # Export as CSV to current dir
pairit data export <configId> --format json        # Export as JSON
pairit data export <configId> --format jsonl       # Export as JSONL
pairit data export <configId> --out ./exports      # Export to specific directory

Add --private if you need to keep an object private. Use --bucket <name> only when you need to override the backend default.

Example

# Point to local manager server (default is http://localhost:3002)
export PAIRIT_API_URL=http://localhost:3002

bun run apps/manager/cli/src/index.ts config upload configs/simple-survey-basic.yaml --config-id simple-survey-basic
bun run apps/manager/cli/src/index.ts config upload configs/agent-study.yaml --config-id agent-study --openai-api-key sk-...
bun run apps/manager/cli/src/index.ts config list
bun run apps/manager/cli/src/index.ts config delete 2f3c4d5e... --force

bun run apps/manager/cli/src/index.ts media upload assets/logo.png
bun run apps/manager/cli/src/index.ts media list
bun run apps/manager/cli/src/index.ts media delete onboarding/logo.png --force

config compile writes configs/simple-survey-basic.json next to the source YAML. config upload defaults the config id to a 16-character base64url string derived from the SHA-256 hash of the compiled JSON (unless --config-id overrides it).

Per-experiment LLM credentials

If your config uses AI agents, attach provider credentials when uploading:

pairit config upload path/to/config.yaml --config-id my-exp --openai-api-key sk-...
pairit config upload path/to/config.yaml --config-id my-exp --anthropic-api-key sk-ant-...

Notes:

• Keys are stored per config, encrypted at rest by the manager server.
• Re-uploading the same configId without a new key keeps the previously stored key for that config.
• That means billing continues on the experimenter's previously uploaded key, not on a shared platform key.
• If an agent uses gpt-* and the config has no OpenAI key, the run fails.
• If an agent uses claude* and the config has no Anthropic key, the run fails.
• There is no global platform-key fallback for experiment agent execution.

data export creates three files in the output directory:

• {configId}-sessions.{format} — session ID, user_state fields (flattened), timestamps, status
• {configId}-events.{format} — session ID, event type, component info, payload, timestamps
• {configId}-chat-messages.{format} — group ID, session ID, sender, content, timestamps

All hosted commands require the manager service to be reachable (Cloud Run deployment or local server). Set PAIRIT_API_URL to point to the desired target. When unset, the CLI defaults to http://localhost:3002.

Development

cd apps/manager/cli
bun run dev
bun run lint

dev runs in watch mode. lint type-checks the TypeScript sources.