loby.

loby.

The canonical CLI for Lob — direct mail, address verification, and campaigns. For humans and AI agents.

$ brew install voska/tap/loby
For AI agents → · Latest release · llms.txt
Recorded against api.lob.com — real responses, real exit codes.

what it does

every Lob resource

All 29 v1 resources behind one binary. Mailers, verifications, campaigns, lookups — same flag conventions, same JSON envelope, same exit codes.

  • postcards
  • letters
  • checks
  • self-mailers
  • snap-packs
  • cards
  • booklets
  • buckslips
  • addresses
  • verify us
  • verify intl
  • bulk verify
  • autocomplete
  • zip lookup
  • geo reverse
  • identity verify
  • campaigns
  • creatives
  • uploads
  • templates
  • informed-delivery
  • bank-accounts
  • billing-groups
  • qr-codes
  • links
  • domains
  • events
  • resource-proofs
  • account

built for agents

Structured stdout, hints on stderr, never mixed. Every mutation is reversible by intent: --dry-run, idempotency keys, semantic exit codes.

  • --json · default for agents
  • --plain · tab-separated
  • --select id,to.city
  • --dry-run on every write
  • --results-only strips envelope
  • --quiet for bare IDs
  • auto idempotency keys
  • 11 stable exit codes

boring stack

Single static Go binary, zero runtime dependencies. Hand-rolled net/http over Lob's API — no third-party HTTP client, no junk transitive deps.

  • Kong CLI parser
  • stdlib net/http
  • 99designs/keyring
  • cosign-signed releases
  • SBOM + provenance attest
  • brew · scoop · curl

for AI agents

The skill is a plain SKILL.md file plus three reference docs — works with any agent framework that reads the canonical ~/.{agent}/skills/<name>/SKILL.md layout (Claude Code, Codex, Factory Droid, etc).

mkdir -p ~/.claude/skills/loby && \
  curl -fsSL lobycli.com/skill/SKILL.md \
    -o ~/.claude/skills/loby/SKILL.md

Pull the full bundle — SKILL.md plus commands, recipes, and resources — from the same URL space at /skill/. The skill teaches the agent to prefer --json, run --dry-run before live mutations, and use loby schema --json as the source of truth.

  • schema loby schema [cmd] --json dumps the full command tree — agents discover the surface without scraping help text.
  • retrieval /llms.txt indexes the skill and reference docs for agent retrieval pipelines.
  • idempotency Every mailer create auto-generates a deterministic key from command + flags + body. Retries on transient failures are safe by default.
  • streams loby events tail --event-type postcard.created --json emits one NDJSON event per line — pipe into jq or a webhook bridge.

exit codes

0success
1error
2usage
3empty result
4auth required
5not found
6forbidden
7rate limited · transient
8retryable · transient
9payment required
10config error

Authoritative: loby exit-codes --json

quick reference

# Authenticate with a test key (test_…) or live key (live_…). $ loby auth login --profile prod # Verify before mailing. $ loby verify us "185 Berry St, San Francisco, CA 94107" --json # Save a recipient. $ loby addresses create --name "Alice Park" --line1 "185 Berry St" \ --city "San Francisco" --state CA --zip 94107 --json # Dry-run a postcard. $ loby postcards create --to adr_… --front @front.html --back @back.html \ --size 4x6 --dry-run --json # Inspect the whole command surface. $ loby schema --json | jq