govcon
v0.3.5
Published
G2X GovCon GTM intelligence in your terminal.
Maintainers
Readme
govcon
G2X GovCon GTM intelligence in your terminal.
govcon brings your G2X account to your terminal, your scripts and your coding agent. Search opportunities, contract awards and companies, see planned buys and recompetes, and read solicitation documents. Search results link to their records in G2X.
Install
You need Node.js 20.19 or later and a G2X account. New to G2X? Create a free account at g2x.com.
npm install -g govcon
govcon --versionTo try it without installing, run npx govcon --help.
Sign in
govcon login # opens your browser to sign in to G2X
govcon whoami # shows who you're signed in as
govcon logout # signs you out on this computerSign in to G2X in your browser as you do on the web, and govcon keeps you signed in on this computer.
On a computer without a browser, such as over SSH:
govcon login --no-browserOpen the address it shows on any device, sign in, and paste back the address your browser ends up on. Over SSH, or on Linux without a display, govcon login does this on its own.
Five useful commands
Find open opportunities:
govcon opportunities "cloud migration" --naics 541512,541519 --limit 8Search inside solicitation documents across SAM, state and local, DLA DIBBS and SBIR/STTR:
govcon documents-search "zero trust architecture" --source sam,sledSee who won similar work:
govcon contracts "help desk" --filter naics=541512 --filter fiscal_year:=2025Find a company, then read its contracting history by UEI:
govcon companies "Leidos"
govcon history UE9QJD4KK1L6 --from-year 2022 --expiring-within 365See planned buys before they're posted:
govcon forecasts "cloud hosting" --agency DHS,VA --fiscal-year 2027Every command has --help. Add --json to any search for output your scripts can read.
Use it from your agent
govcon mcp add claude # Claude Code
govcon mcp add cursor # Cursor
govcon mcp add codex # Codexgovcon mcp add sets up Cursor for you, and prints the one command to run for Claude Code or Codex. Your agent then gets G2X's research tools through govcon mcp serve, which runs on your computer with your sign-in. It offers only the tools that read, so your agent can't change anything in your G2X account. To teach your agent when to use govcon, add its skill:
govcon skills install --host claude,codex,cursorThe sections below have every command, and the details for each agent.
Commands
Every command that reads from G2X accepts --json. List flags take comma-separated values. Commands whose results continue on another page accept --cursor, and govcon prints the exact command for the next page.
Opportunities
govcon opportunities "cloud migration" --naics 541512,541519 --limit 8
govcon documents-search "zero trust architecture" --source sam,sledopportunities searches open federal opportunities (up to 8 results). documents-search finds opportunities by the text inside their documents (statements of work, specifications, Q&A) across SAM, state and local (SLED), DLA DIBBS and SBIR/STTR, and shows the matching passages. It takes --filter too, including lists of numbers and a date or number range:
govcon documents-search "zero trust" --filter active:=true --filter 'posted_range:={"gte":"2026-01-01"}'Contracts, awards, vehicles, protests and grants
govcon contracts "help desk" --filter naics=541512 --filter fiscal_year:=2025
govcon awards --type idvs "enterprise infrastructure"
govcon vehicles "OASIS+"
govcon protests --filter outcome=Denied
govcon grants "rural broadband"
govcon search subawards "cybersecurity" # any datasetsearch <dataset> works for every G2X dataset: opportunities, contracts, idvs, vehicles, protests, forecasts, grants, subawards, otas, entities, notices, agencies, naics, psc. contracts, idvs, vehicles, protests and grants are shortcuts for it, and awards --type contracts|idvs|subawards|otas covers the award datasets.
Narrow any of them with --filter key=value, repeated as needed. A value is text; a comma makes a list (--filter agency_code=9700,3600). Use key:=value for a number, true or false, or a JSON list of text (--filter fiscal_year:=2025). If a dataset doesn't take a filter, the error names the filters it does take. --limit goes up to 50.
Companies
govcon companies "Leidos"
govcon record company UE9QJD4KK1L6
govcon graph UE9QJD4KK1L6 --per-relation 5 # agencies, vehicles and partners it's connected to
govcon history UE9QJD4KK1L6 --from-year 2022 --expiring-within 365
govcon socioeconomic UE9QJD4KK1L6 # small-business certifications
govcon teaming 541512 --exclude UE9QJD4KK1L6 --min-awards 5
govcon people "contracting officer" --company UE9QJD4KK1L6history shows a company's contracting portfolio by UEI: prime awards, the IDVs it holds and its contract vehicles, plus the awards ending soonest with --expiring-within <days>. teaming finds companies with past performance in a NAICS code, with their set-aside certifications; --exclude leaves out your own company or competitors.
Forecasts, recompetes and expiring awards
govcon forecasts "cloud hosting" --agency DHS,VA --fiscal-year 2027
govcon recompetes --uei UE9QJD4KK1L6 --from-month 3 --to-month 18
govcon expiring --agency-code 9700 --fiscal-year 2027 --min-obligated 1000000
govcon vehicle-usage "OASIS+"forecasts finds planned buys that aren't solicited yet. Filters: --agency (acronyms), --naics, --status, --fiscal-year, --award-after, --award-before.
recompetes lists contracts ending in a window, yours or a competitor's, each with the open opportunities that could be its recompete and how confident the match is. Filters: --uei (up to 10), --office, --naics, --psc, --from-month and --to-month (months from today, default 0 to 12).
expiring lists awards whose period of performance ends in a fiscal year or date window. Filters: --type contracts|idvs, --agency-code, --fiscal-year, --ends-after, --ends-before, --min-obligated, --naics, --psc, --uei.
Opportunity documents
govcon record opportunity <opportunity_id>
govcon attachments <opportunity_id> # the source documents on file, and whether their text can be read
govcon read <opportunity_id> <attachment_id> # the document as Markdown
govcon read <opportunity_id> <attachment_id> --page 3 # one page
govcon read <opportunity_id> <attachment_id> --format json > sow.jsonread prints the whole document, exactly as G2X holds it, so you can pipe it or save it. It checks that every part arrived and matches the document before printing anything, so a document is never printed half-read. Documents up to 256 MB are read whole; read a larger one a page at a time with --page.
Events and parts
govcon events cyber --from 2026-10-01 --state VA
govcon event <name-from-its-link>
govcon nsn 5340-01-234-5678
govcon parts --name "hydraulic pump" --fsc 4320Usage
govcon usage # how much you've usedAny tool
govcon tools # list the G2X tools govcon can call
govcon tools g2x_search_records # show a tool's input schema
govcon call g2x_search_records --input '{"dataset": "protests", "query": "cloud"}'
echo '{"record_type": "company", "id": "UE9QJD4KK1L6"}' | govcon call g2x_get_record --input-file -Maintenance
govcon upgrade # check for a newer release and show the upgrade command
govcon upgrade --check # only report
govcon --help # every command has --helpUse with coding agents (MCP)
govcon mcp serve is an MCP server that runs on your computer and gives your coding agent G2X's research tools: opportunities, companies, awards, forecasts, recompetes, events, supply items, contract history, teaming partners, opportunity documents and your usage. It offers only the tools G2X labels as read-only and checks that label again before every call, so none of them change anything in your G2X account. It uses your sign-in from govcon login, so sign in first. Nothing secret is written into your agent's settings.
Claude Code
govcon mcp add claudeThis prints the command to run:
claude mcp add --scope user govcon -- govcon mcp serveCursor
govcon mcp add cursorThis adds the server to ~/.cursor/mcp.json. It never overwrites a file that isn't valid JSON, or a govcon entry you've customized. Add --print to see the entry without changing anything:
{ "mcpServers": { "govcon": { "command": "govcon", "args": ["mcp", "serve"] } } }Codex
govcon mcp add codexThis prints the command to run, codex mcp add govcon -- govcon mcp serve, and the matching ~/.codex/config.toml entry.
If your agent can't find govcon, replace govcon in its settings with the full path that which govcon prints.
Agent skill
govcon includes a skill that teaches coding agents when and how to use it:
govcon skills list
govcon skills install --host claude,codex,cursor # into this project
govcon skills install --global # into your home folder, for the agents found thereClaude Code reads .claude/skills. Codex and Cursor read .agents/skills.
JSON output
--json prints the result under data, and data.kind names its shape: opportunity_search, company_search, record, graph, dataset_rows, detail, usage, or a document. govcon read --json prints one JSON object with the whole document's text as text:
{ "ok": true, "data": { "kind": "dataset_rows", "title": "...", "rows": [{ "id": "...", "title": "...", "record_url": "https://g2x.com/app/...", "facts": {} }], "total": 12, "next_cursor": "..." } }When a result may be missing some matches, data.provenance.outcome is "partial", and the command still exits 0.
When a command fails with --json, the failure is printed to stdout and the command exits with a non-zero code:
{ "ok": false, "schema_version": "2026-09-01", "error": { "code": "rate_limited", "message": "...", "retryable": true } }govcon tools <name> --json prints that tool's definition, including its input schema.
Exit codes
| Code | Meaning | | --- | --- | | 0 | Success | | 1 | G2X could not complete the request (the message says why), or an unexpected error | | 2 | Invalid command, arguments, or input | | 3 | Not signed in, the sign-in has ended, or sign-in was cancelled | | 4 | Not included in your plan | | 5 | Not found | | 6 | Rate limited | | 7 | G2X is temporarily unavailable or could not be reached |
Sign-in and security
govcon loginuses your browser and G2X's own sign-in page;govconnever sees your password. The browser is handed a page in~/.govconthat only you can read, which forwards it to G2X, so the sign-in address never appears in the list of running programs. The browser returns togovconathttp://127.0.0.1on this computer, on port 53682, 53683 or 53684, and only a return that matches the sign-ingovconstarted is accepted.- Your sign-in (an access token and a refresh token) is saved in
~/.govcon/credentials.json. The folder is created with mode 0700 and the file with mode 0600.govconrenews it on its own before it expires, andgovcon logoutends it at G2X and removes the file. - It is sent only to G2X, over https, and
govcondoesn't follow redirects. govconnever prints your sign-in. If anything G2X sends contains it, however it's written, that field is withheld and shown as "This field was withheld because it contained your G2X sign-in." Anything else shaped like a sign-in or a G2X key is shown as[redacted]orqs_[redacted]. Both apply in text and in--json.- Everything G2X sends has terminal control characters and invisible formatting characters removed before
govconshows it or prints it as JSON, so a record, a document or a message can't change your terminal or hide text.govcon readoutput that is piped or saved to a file is exact, unless the document contains your sign-in or anything shaped like a secret.
Configuration
| Variable | Purpose |
| --- | --- |
| G2X_MCP_URL | The G2X research connection every command uses, default https://mcp.g2x.com/mcp/research |
| BROWSER | The command govcon login opens the sign-in address with, instead of your default browser |
| NO_COLOR | Turn off colored output |
Terms
Use of G2X through govcon is subject to the G2X Community Member Guidelines, including the API access terms: https://g2x.com/community-member-guidelines#api-access
Uninstall
govcon logout
npm uninstall -g govcon # if you installed globally
rm -rf ~/.govconContributing
G2X doesn't accept external contributions to govcon. To report a problem or ask for a feature, contact https://g2x.com/support. Report a security issue privately through https://g2x.com/support (choose "Report an issue"), with the version from govcon --version; leave anything from ~/.govcon out of the report.
License
MIT. See LICENSE.
