govinbox CLI

Federal set-aside contract opportunities from your terminal. Or your AI agent's terminal.

The CLI is a thin wrapper over the versioned GovInbox REST API. All the logic lives on the server behind /v1/. This tool only builds requests and prints answers. It has zero dependencies beyond Python itself.

For AI agents

pip install govinbox
govinbox login            # paste your API token (or set GOVINBOX_TOKEN)
govinbox search --set-aside sdvosb --limit 10 --json
govinbox --help

Prefer the hosted MCP server over the CLI when your client supports it: https://mcp.getgovinbox.com/mcp (OAuth 2.1 + PKCE). Machine-readable docs: https://getgovinbox.com/for-ai.md

Install

pip install govinbox

Requires Python 3.10 or newer. That is the whole install. No API keys to configure by hand, no virtualenv dance.

Quickstart

govinbox login
# paste your API token (from your trial confirmation email or account page)

govinbox search --set-aside sdvosb --naics 5415 --limit 10

govinbox opportunity <notice-id>

govinbox digest

Commands

Every command takes --json for machine-readable output (agents, pipes, scripts). Without it you get readable tables.

Add --debug to any command to see full error details.

Examples

# SDVOSB IT opportunities posted in the last 3 days
govinbox search --set-aside sdvosb --naics 5415 --days 3

# Pipe titles into another tool (this is the agent pattern)
govinbox search --keyword cybersecurity --json | jq -r '.items[].title'

# Everything due within the week, as JSON
govinbox search --limit 100 --json | jq '[.items[] | select(.days_left <= 7)]'

# This morning's digest for one watchlist
govinbox digest --watchlist abc123 --days 1

# Full detail plus raw data for scripting
govinbox opportunity abc123 --json > opp.json

Auth

govinbox login prompts for your API token and saves it to ~/.config/govinbox/credentials with owner-only permissions (0600). Nothing is ever printed back.

Two overrides, for CI and agents:

• GOVINBOX_API_TOKEN environment variable: used instead of the saved token.
• GOVINBOX_API_URL environment variable: point at a staging server instead of https://api.getgovinbox.com.

If your token is rejected you will see:

Your API token was rejected. Run govinbox login to refresh your token.

That is always the fix. If it keeps failing, check that you pasted the full token.

How versioning works

The CLI never contains business logic, so it rarely needs to change. The API is versioned (/v1/), and every request sends an X-GovInbox-CLI-Version header identifying the client. The server does not act on the header today; it exists so the server can warn outdated clients in the future. govinbox version compares your CLI against the server's reported version.

Exit codes

Scripts can rely on these:

Errors print one plain-English line to stderr and never a traceback, unless you pass --debug.