Metadata-Version: 2.4
Name: govinbox
Version: 1.0.0
Summary: GovInbox CLI: federal set-aside contract opportunities from your terminal or your AI agent
Author: Artifex Innovations LLC
License: Proprietary
Keywords: mcp,model-context-protocol,sam.gov,federal-contracts,set-aside
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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

```bash
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

```bash
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

```bash
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.

| Command | What it does |
|---|---|
| `govinbox login` | Save your API token on this machine (stored at `~/.config/govinbox/credentials`, readable only by you). The token is verified against the server; if it fails, nothing is kept. |
| `govinbox logout` | Remove the saved token. |
| `govinbox whoami` | Check the saved token is valid and show how many watchlists you have. |
| `govinbox search` | Search opportunities. Filters: `--set-aside` (sdvosb, 8a, hubzone, wosb, veteran, indian, smallbiz), `--naics` (prefix like 5415), `--keyword`, `--agency` (e.g. "veterans affairs"), `--days` (default 7), `--limit` (default 25). |
| `govinbox opportunity <id>` | Full details for one opportunity, including the SAM.gov link and early signals. |
| `govinbox watchlists` | List your saved searches. |
| `govinbox watchlist <id>` | Show one saved search. |
| `govinbox digest [--watchlist <id>] [--days N]` | New matches for your watchlists, plain-English lines, newest first. |
| `govinbox version` | CLI version, API endpoint, and server version. |

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

## Examples

```bash
# 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:

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error (bad arguments from the server, network failure, unexpected error) |
| 2 | Not logged in, or the token was rejected (`govinbox login` is the fix) |
| 3 | Subscription lapsed (HTTP 402) |
| 4 | Rate limited (HTTP 429; the message tells you when to retry) |
| 5 | Not found (HTTP 404) |
| 6 | Bad request (HTTP 400) |
| 130 | Cancelled with Ctrl-C |

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