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, run AI voice interviews, 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.11+. Some commands need extra tooling:
showreelrequiresffmpegon yourPATH(brew install ffmpeg).synthrequires the optionalsynthextra:pip install 'podojo-cli[synth]'thenplaywright 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:
- Environment variables —
PODOJO_API_KEY,PODOJO_BASE_URL ~/.podojo.toml- 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 and get-doc accept brief, agent, and final document types.
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
A user test can open with an optional participant screener: on-screen
single-select screening_questions whose options carry qualifies: true
flags. Participants must pick a qualifying option on every question; everyone
else sees the test's rejection_message and never reaches the recorded test.
See podojo usertests example for the exact shape.
Set required_device: mobile or required_device: desktop to restrict a test
to one kind of device. Participants who open the link on the other kind are
asked to switch over before the welcome screen, so they never start a screener
or use up a session. Tablets count as mobile.
AI interviews
An AI interview is a self-serve voice conversation: an AI interviewer asks your questions in order and adaptively follows up. One YAML file defines one study:
podojo aiinterviews example > my-interview.yaml # print a template to start from
podojo aiinterviews validate my-interview.yaml # check it without creating
podojo aiinterviews create -f my-interview.yaml
podojo aiinterviews list
podojo aiinterviews get checkout-experience-v1
podojo aiinterviews update checkout-experience-v1 -f changes.yaml
podojo aiinterviews delete checkout-experience-v1
create and get print the participant Preview and Live URLs. The frontend
base URL can be overridden via ai_interviews_url in ~/.podojo.toml or
PODOJO_AI_INTERVIEWS_URL.
A study can open with optional on-screen screening_questions (closed
multiple-choice questions; multi_select: true allows several picks). Answers
are recorded with each session. A question marked screener: true also gates
entry: its options carry qualifies: true flags, and participants who don't
pick a qualifying option see the study's rejection_message and never reach
the voice interview. A question can carry a show_if condition to appear only
when an earlier question was answered with specific options. See
podojo aiinterviews example for the exact shape.
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
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for podojo-cli 1.19.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| podojo_cli-1.19.0.tar.gz | 74.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| podojo_cli-1.19.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 112.7 kB
Release files / podojo_cli-1.19.0.tar.gz
| Download URL | podojo_cli-1.19.0.tar.gz |
|---|---|
| Size | 74.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
70594a7282b3f0c9e39a965e54a0868d1dcb436517abcfc47c929613ed1b4927
|
|
BLAKE2b-256 checksum How to use checksums |
b2c096d236d03bacbb474d799b6b77621c510450f1ca50066c3810ab68e3d51e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 19, 2026.
Transparency logRelease files / podojo_cli-1.19.0-py3-none-any.whl
| Download URL | podojo_cli-1.19.0-py3-none-any.whl |
|---|---|
| Size | 37.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
98c2d4108639f0e004c905f916a96e8a3f33902b71cc7090ebbf33cfcdfcf21e
|
|
BLAKE2b-256 checksum How to use checksums |
9e84885e426089fe5a45ee4063b1994aeb89e3e0cfec3c340e5bdbcd39b98ab1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 19, 2026.
Transparency log
