CLI

papercrane, in your terminal.

The CLI is the fastest path from a target PDB to a ranked FASTA. Everything you can do in the dashboard: submit campaigns, watch logs, pull designs: is one command away.

Install →Back to docs HTTP API

01Install

Homebrew is the recommended path on macOS and Linux. An npm fallback is provided for CI runners and Windows.

shell

# Homebrew (recommended)
brew install papercrane-bio/papercrane/papercrane

# npm fallback
npm i -g @papercrane/cli

output

==> Pouring papercrane--0.4.2.arm64_sonoma.bottle.tar.gz
  /opt/homebrew/Cellar/papercrane/0.4.2: 14 files, 8.7MB
papercrane --version
0.4.2

02Authenticate

papercrane login opens your browser to a one-time auth callback. The token is written to ~/.config/papercrane/config.toml with mode 600.

shell

papercrane login

output

? How would you like to log in?
  > OAuth (open browser)
    Paste API key
i Open this URL in your browser:
  https://api.papercrane.bio/cli-auth?cb=…
✓ API key saved to ~/.config/papercrane/config.toml (chmod 600)
i Logged in as you@lab.org (Org: rosen-lab, Tier: pro)

NOTEFor CI, pass --api-key non-interactively or set PAPERCRANE_API_KEY.

03Submit a job

One call. Pick a project, a tool, a target, and the hotspots that matter. The CLI returns the job id immediately and queues the run.

shell

papercrane jobs submit \
  --project pdl1-binders \
  --tools boltzgen \
  --target 5J89 \
  --hotspots A:42,A:87 \
  --num-designs 1

output

⠋ submitting job
✓ submitted job_8f3c1a92ee → queued

04List jobs

See what's running, done, or failed. Filter by status and pipe --json into jq for scripting.

shell

papercrane jobs list --status running

output

ID            TOOL       STATUS    DESIGNS  SUBMITTED
job_8f3c1a92  boltzgen   running   0/1      2026-04-29 14:11

05Export designs

Pull a multi-FASTA of every design from a job (or filter by project), or download a single structure as cif/pdb/fasta for downstream tools.

shell

# Multi-FASTA of a whole job
papercrane designs export-fasta \
  --job job_8f3c1a92ee \
  --out designs.fasta

# Single structure
papercrane designs download des_91f0a2 --format fasta

output

✓ wrote 87 sequences → designs.fasta
✓ saved ./des_91f0a2.fasta

06API keys

API keys (with scopes like designs:read, jobs:write) are issued and revoked from the dashboard. Once you have a key, papercrane login --api-key <KEY> wires it into your shell config.

shell

# After creating a key in the dashboard:
papercrane login --api-key pcr_live_…

output

✓ API key saved to ~/.config/papercrane/config.toml (chmod 600)
i Logged in as ci-bot@lab.org (Org: rosen-lab, Tier: pro)

NOTEProgrammatic key creation lands with the v0.5 CLI: use the dashboard for now.