Tamarind CLI

Command-line interface for the Tamarind Bio platform. Discover tools, submit and monitor protein / nucleic-acid / small-molecule jobs, and download results — from your terminal, a script, CI, or an AI coding agent (Claude Code, Codex, …).

The CLI is a thin client over the same API the Tamarind MCP server uses, so the two stay in lockstep. See docs/architecture.md for how drift is prevented.

Install

uv tool install tamarind-cli      # or: pipx install tamarind-cli

Or with the bootstrap installer (uses uv, pipx, or Python/pip already on your PATH):

curl -fsSL https://app.tamarind.bio/cli/install.sh | sh

To track the repo directly instead of the PyPI release:

uv tool install "git+https://github.com/Tamarind-Bio/tamarind-cli"
# or: pipx install "git+https://github.com/Tamarind-Bio/tamarind-cli"

Releasing: tag a GitHub Release and the publish.yml workflow builds and uploads to PyPI via Trusted Publishing (configure the trusted publisher for tamarind-cli on PyPI first).

Authenticate

Get an API key from the Tamarind web app (Settings → API), then either:

export TAMARIND_API_KEY="sk_..."      # best for agents / CI
# or
tamarind auth login                    # stores it in ~/.tamarind/config.json
tamarind auth status

Quickstart

# 1. Find a tool
tamarind tools --function structure-prediction --modality protein
tamarind tools --search boltz

# 2. Inspect its parameters and grab a runnable example
tamarind schema boltz
tamarind schema boltz --example > job.yaml   # most tools ship an example; some don't

# 3. Validate, then submit
tamarind validate boltz --input job.yaml
tamarind submit boltz --input job.yaml --name my-run \
  --wait --timeout 3600 --download ./out

# 4. Monitor / fetch
tamarind jobs
tamarind status my-run
tamarind results my-run --download ./out

Set individual fields inline instead of a file:

tamarind submit boltz \
  --set inputFormat=sequence \
  --set sequence=MKTVRQERLKSIVRIL... \
  --name quick-fold

Output for agents

Every command emits JSON when stdout is not a TTY, or with --json. Result documents are written to stdout. Typed command, transport, and usage errors are written to stderr as {"error":{"type":...,"message":...,"exitCode":...,"detail":...}}; detail is omitted when unavailable. A domain verdict can deliberately combine a nonzero exit with a result document: invalid validate output remains on stdout with exit 5, and a terminal unsuccessful job remains on stdout with exit 9 so callers can inspect its status. Exit codes are stable: 0 ok, 1 generic failure, 2 usage, 3 auth, 4 not-found, 5 validation, 6 rate-limit, 7 timeout (a bounded wait elapsed while the remote job may still run), 8 budget/quota exhaustion, and 9 remote job failure.

For agent workflows, always put a deadline on blocking commands. submit --wait and results --wait accept --timeout; the standalone wait command remains the easiest way to reattach to a durable job name.

Starting in 0.2, results requires --download DIR by default and never prints a presigned URL implicitly. This intentional safety boundary is why the release uses a new pre-1.0 minor version. The explicit --show-url escape hatch returns a credential-bearing, short-lived URL; do not use it in agent, CI, or shared logs.

Not every tool ships a runnable example — schema <tool> --example exits non-zero (with a clear message) when one isn't available, so a > job.yaml redirect never silently produces an empty file. Destructive commands (delete, files delete) require --yes/-y when run non-interactively (piped or --json), so an agent never removes data without an explicit confirmation.

tamarind --json jobs | jq '.jobs[] | select(.JobStatus=="Running")'

--json, --profile, and the endpoint/auth overrides are global options, so place them before the command name.

Commands

Run tamarind <command> --help for full options.

Configuration

Profiles (key + endpoints) are stored in ~/.tamarind/config.json. Use a profile to point at staging:

tamarind --profile staging --api-base https://staging.tamarind.bio/api/ auth login
TAMARIND_PROFILE=staging tamarind tools

Links

• CLI docs — the hosted quickstart and command reference
• MCP server — the hosted option for claude.ai, ChatGPT, and other MCP clients
• API key — get your key and review rate limits

Questions or need help? Contact us at info@tamarind.bio.

License

Licensed under the Apache License 2.0.