Bison CLI

What it can do

Every Bison endpoint, composable into repeatable workflows. No UI needed.

campaign

Create, list, pause, resume, stats, events, chart data, sender management, lead operations.

leads

Upsert, validate, search, update status, unsubscribe, blacklist. Batch 500 per request.

sequence

View, create, update, activate variants, test-email, delete steps. v1.1 endpoints.

replies

List, get, thread view, mark interested/uninterested, compose, reply, forward, templates.

sender-emails

List all accounts, MX record check (single or bulk), warmup enable/disable/limits.

workflow

10 commands Composable pipelines: setup, upload, health, duplicate, teardown, reactivate, rotate, expand, prep-senders, presets.

blacklist

Manage email and domain blacklists. Add, bulk CSV import, remove/unblock entries.

workspace

List, set, status. Persistent state file for humans, per-command --workspace override for scripts.

Printing Press workflows

Single commands that chain atomic primitives into named, documented, repeatable operations. Each produces structured JSON output for agent and human consumption.

Command	What it does	Dry run?
`workflow setup`	Create campaign + settings + schedule + sequence in one shot	✓
`workflow upload`	Validate → preview → upsert → attach → verify. Detects active campaigns.	—
`workflow health`	Health check across all active campaigns. Flags underperformers by reply rate.	—
`workflow duplicate`	Clone a campaign, rename, optionally swap leads for A/B testing	—
`workflow teardown` new	Pause → export stats + events → summary JSON. Continues past read-only failures.	✓
`workflow reactivate` new high blast radius	Pause source → create new campaign → move leads → attach inboxes → checkpoint.	✓
`workflow rotate` new	Warmup check → attach new senders → remove old. Attach-before-remove ordering prevents 0-sender gaps.	—
`workflow expand` new	Clone structure → upload fresh leads → attach inboxes → verify lead count. Setup+upload pattern prevents cross-contamination.	—
`workflow prep-senders` new	MX check-all → warmup list → attach to campaign. One command for pre-flight checks.	—
`workflow presets`	Show all available campaign setting presets	—

How it works

Three layers: HTTP client, atomic commands, composable workflows.

Retry

3 retries with exponential backoff, 429 rate-limit handling, 120s timeout per request.

Batch

500 leads/req — the Bison API limit. Auto-batches uploads and attachments across requests.

Workspace

Per-command --workspace N override for scripts, or persistent .bison_state.json for interactive use.

Pagination

Auto-paginates Laravel endpoints. --limit 0 = pull all pages. --per-page N controls chunk size.

Errors

Typed exceptions: BisonAuthError, BisonNotFoundError, BisonValidationError, BisonAPIError.

JSON

All commands output parseable JSON to stdout. Progress and warnings go to stderr. Agent-friendly by design.

Code examples

Every operational pattern, one command.

# Launch a new campaign
py bison_cli.py --workspace 3 workflow setup   --name "Client-Segment-May2026"   --preset standard   --sequence-file seq.json
py bison_cli.py --workspace 3 workflow upload   --campaign-id 728 --file leads.json

# Rotate inboxes on a running campaign
py bison_cli.py --workspace 3 workflow rotate   --id 728   --new-inbox-ids 12,13,14

# Health check across all active campaigns
py bison_cli.py --workspace 3 workflow health --days 7

# Tear down a campaign (dry run first)
py bison_cli.py --workspace 3 workflow teardown   --id 728 --dry-run
py bison_cli.py --workspace 3 workflow teardown --id 728

# Pre-flight sender check before launch
py bison_cli.py --workspace 3 workflow prep-senders --campaign-id 728

# Expand winning campaign to new segment
py bison_cli.py --workspace 3 workflow expand   --source-id 728   --name "Client-NewSegment-May2026"   --leads-file new-segment.json   --inbox-ids 5,6

# Reactivate dead leads with fresh copy
py bison_cli.py --workspace 3 workflow reactivate --dry-run   --source-id 728   --name "Client-Reactivation-May2026"   --sequence-file new-seq.json   --inbox-ids 5,6

Get started

Python 3.10+, an API key, and 3 dependencies.

# Clone and install
git clone https://github.com/LeadGrowGTM/bison-cli.git
cd bison-cli
pip install -r requirements.txt

# Set your API key
echo BISON_API_KEY=your_key_here >> .env

# First-run setup (validates key, selects workspace, configures MCP)
py bison_cli.py setup

# Set workspace and go
py bison_cli.py workspace set --id 3
py bison_cli.py campaign list

# Run tests (124 mocked, safe to run anywhere)
py -m pytest test_bison_cli.py -v

Dependencies: click ≥ 8.0, requests ≥ 2.28, python-dotenv ≥ 1.0. Tested on Python 3.10+. 124 regression tests, all mocked — safe to run anywhere.

API key location: Hardcoded to C:/Users/mitch/Everything_CC/.env for the main workspace. For other environments, set BISON_API_KEY, EMAIL_BISON_API_KEY, or EMAILBISON_API_KEY in a local .env file.