podojo-cli 1.0.0

CLI for the Podojo user research platform

podojo-cli

Command-line tool for the Podojo user research platform.

podojo lets UX researchers manage projects, upload and transcribe interviews, build unmoderated user tests, download research videos, cut showreels, and run synthetic test participants — all without leaving the terminal.

Installation

uv tool install podojo-cli

Or with pip:

pip install podojo-cli

Requires Python 3.12+. Some commands need extra tooling:

• showreel requires ffmpeg on your PATH (brew install ffmpeg).
• synth requires the optional synth extra: pip install 'podojo-cli[synth]' then playwright install chromium.

Authentication

Log in once with your Podojo API key — it's stored in your system keychain:

podojo auth login            # prompts for the key
podojo auth login --key XXX  # or pass it directly
podojo auth logout           # remove the stored key

Configuration is read from, in order of precedence:

1. Environment variables — PODOJO_API_KEY, PODOJO_BASE_URL
2. ~/.podojo.toml
3. The system keyring (set by podojo auth login)

Usage

podojo --help            # top-level help
podojo <group> --help    # help for a command group

Projects

podojo projects list
podojo projects create "Checkout Redesign" --brief "Q1 usability study"
podojo projects upload-doc "Checkout Redesign" brief.md --type brief
podojo projects get-doc "Checkout Redesign" --type final -o final-report.md

upload-doc accepts brief and final document types; get-doc also supports agent. Embedded images are stripped from markdown before upload.

Interviews & transcripts

podojo interviews upload session-03.mp4 --project "Checkout Redesign"
podojo transcripts list "Checkout Redesign"
podojo transcripts download "Checkout Redesign" <batch-id> -o transcript.txt

Videos & showreels

podojo videos list "Checkout Redesign"
podojo videos download <batch-id> -o clip.mp4
podojo showreel create clips.json -o showreel.mp4

The showreel clips.json is a list of clips, each with batch_id, participant, country, topic, start, and end (MM:SS or HH:MM:SS). Each clip gets an auto-generated title card.

Unmoderated user tests

podojo usertests example > my-test.yaml   # print a template to start from
podojo usertests validate my-test.yaml    # check it without creating
podojo usertests create -f my-test.yaml
podojo usertests list
podojo usertests get checkout-usability-v1
podojo usertests update checkout-usability-v1 -f changes.yaml
podojo usertests delete checkout-usability-v1
podojo usertests snippet                  # recorder script for self-hosted prototypes

Synthetic participants

The synth group drives a Playwright browser through a user test preview so an agent (e.g. Claude Code) can act as a synthetic participant:

podojo synth start checkout-usability-v1   # or a preview URL
podojo synth state
podojo synth click "Get Started"
podojo synth fill "#answer" "It felt slow"
podojo synth advance
podojo synth stop

Links

• Source & issues
• Changelog

License

MIT