Open Agent Guide client

Open Agent Guide is a verifiable directory of AI products. It records each product's capabilities, pricing, compliance, and agent-facing affordances, such as APIs, SDKs, MCP servers, and CLIs. It grades each product on an AI-native score.

oag is the command-line client for Open Agent Guide. Use it for two tasks:

• Read the catalog. Search products, read one product with its related records, and page through results. Catalog reads are public, so you need no account and no token. This is what most people use the client for.
• Submit catalog proposals. Validate a batch, submit it, and watch each proposal to a terminal state. Submission needs a bearer token.

The open-agent-guide package also ships oag_client, a typed Python library that runs the same read and submission workflows from your own code.

• Distribution open-agent-guide on PyPI. Import oag_client. CLI oag.
• Documentation: https://www.openagentguide.com/developers/
• MIT licensed.

Install

The client supports macOS and Linux on Python 3.12, 3.13, or 3.14.

pip install open-agent-guide        # library + oag CLI
uv tool install open-agent-guide    # isolated CLI install

To upgrade, run pip install --upgrade open-agent-guide or uv tool upgrade open-agent-guide. To use the library in a project, run uv add open-agent-guide. The client does not support Windows yet. The client does not support standalone executables yet.

Tutorial: read the catalog

This tutorial shows a first read from start to end. Catalog reads are public, so you need no token.

List products. The client prints the server body as JSON.

oag products list

The response holds a count, a results array, and a next link. Read one product by its slug or its UUID.

oag products get <slug>

Search products by text.

oag products list --search "code review"

Expand related records in the same read. Name the relations you want.

oag products get <slug> --expand mcp_servers,api_specs

Read every page in one array. The client follows each next link for you.

oag products list --all

OAG_BASE_URL sets the API origin. It defaults to https://www.openagentguide.com. Point it at a staging origin to test. OAG_BASE_URL cannot contain credentials. It cannot contain a path, a query, or a fragment. The client does not follow redirects.

How-to guides

Search and filter products

Combine filters with --search and with each other.

oag products list --has-mcp --tier A
oag products list --category code-generation
oag products list --organization anthropic

Pass any other server filter with --filter KEY=VALUE. Repeat the option for more filters.

oag products list --filter open_source=true --filter has_cli=true

List every filter the command accepts with oag products filters. The server rejects an unknown filter with a 400 that names the bad key.

oag products filters
oag products filters --output json

Read one product with its related records

Request related records with --expand. Select a subset of top-level fields with --fields.

oag products get <slug> --expand organization,capabilities,api_specs
oag products get <slug> --fields name,ai_native_score,ai_native_tier

Page through a large result set

Set the page size with --page-size. Read every page in one JSON array with --all; the client follows each next link for you.

oag products list --page-size 50
oag products list --all

The server bounds page sizes. The response reports page_size_default and page_size_max.

Submit a batch and watch it

Submission needs a bearer token. Generate a token in your account settings and export it.

export OAG_TOKEN=...

1. Validate the batch: oag validate batch.json --output json. Validation calls the server and reports its field-path errors.
2. Submit the batch with a journal: oag submit batch.json --journal batch.journal.json --output json. The journal lets you resume the batch and reconcile it later.
3. Watch the submissions with a journal and a timeout: oag watch --file ids.txt --journal watch.journal.json --timeout 900 --output jsonl. The client polls each unresolved submission until it reaches a terminal state.

Use one pacing directory for concurrent validate, submit, and watch commands. Bearer tokens never appear in transport diagnostics. Catalog proposals are immutable once created.

Explain a rejection

Run status or watch with --output explain to read why a submission needs work.

oag status 00000000-0000-0000-0000-000000000001 --output explain

--output explain (-o explain) drops the full record dump. It prints a compact, line-based explanation of each result:

• the lifecycle state, the next-action guidance, the terminal resolution, and any successor IDs;
• for each failed or errored check, the headline summary, then every unsupported claim with its verdict, its specific reason, and its citation URLs;
• the decision basis that closes each check.

The view keeps the claim-level reason a repair depends on, so the fix is never hidden behind a broad diagnostic category. It reads only the fields the read API already returns to you: guidance, resolution, and the scrubbed check_feedback projection. It makes no extra server call. The json and jsonl contracts and the journal format stay unchanged.

Retire a submission

retire withdraws or supersedes one of your open submissions.

• To withdraw the proposal, pass no --successor option.
• To supersede the proposal, pass one or more --successor UUID options. Each option names an explicit newer replacement.
• To record an optional reason, pass --reason TEXT.

oag retire 00000000-0000-0000-0000-000000000001 --force --reason "stale"
oag retire 00000000-0000-0000-0000-000000000001 --force --successor UUID --output json

retire requires --force. Without --force, it refuses, sends nothing, and exits 2. A success reports the server's disposition (withdrawn or superseded) and exits 0. The command does not poll afterward. Use status or watch to follow the retired submission and its successors. See the retire entry under Reference for the full behavior and the server rules.

Recover after a timeout and reconcile a journal

A watch timeout does not mean a submission failed. Resume its journal. Inspect the lifecycle and the terminal evidence.

Reuse the original submit journal and idempotency keys after an uncertain create. Never start a duplicate batch to beat a deadline.

A pacing timeout reports the lane, the reserved wait, the remaining budget, and the requests that the client sent. Submit journals keep this diagnostic with the original idempotency key. Watch adds deadline_error to unresolved records and saves it in the watch journal. Watch keeps earlier read errors and submission snapshots. Resume the same journal with a larger budget after you investigate shared load. Never clear the pacing file to skip a cooldown. Never delete the journal to retry uncertain submissions.

Some older entries have no keys. The client cannot replay them safely. Inspect your submissions on the server across all statuses. Compare the complete payload and the submitter. Once you positively identify an ID, associate it with the input row:

oag reconcile batch.json --journal batch.journal.json --row 2 --id UUID

This checks that the ID is readable. You verify the row-to-ID match. It does not create or edit a server submission. If no match turns up, absence is not proof of failure. Reconcile with an administrator before you create a new batch and journal.

A server 409 idempotency_key_reused also needs inspection. Do not mint a fresh key for the uncertain write. The effective callback URL must stay the same for a retry; a change to a token's default callback can cause that conflict.

For a definitively failed row, correct the payload. Submit a new batch with a new journal. Existing submissions are immutable. To supersede a stalled open create, inspect the existing submission. Then set "force": true in a new payload and submit with a new journal. The client never adds force. The client never edits an existing proposal. Keep prior journals for audit.

Research a product's coverage gaps

Run oag coverage PRODUCT --output json for one compact report of a product's coverage and its unknown scored fields. The default text output adds evidence guidance. Read each gap's shared semantics, its schema reference, and its absence page class before you draft. Keep unsupported values unknown. A confirmed absence can improve coverage without improving the AI-native score. Use submission validation to inspect projected changes after you collect evidence.

Share pacing across workers

To coordinate workers on one host, point them at the same pacing directory, the same API origin, and the same token. Set OAG_PACING_DIR to choose the directory; it defaults to oag-client-pace under the system temp directory. The client then shares its reservations and Retry-After cooldowns across those processes, so they stay under the server's quotas together. The population benchmark and the pi submitter opt into this coordination.

Separate directories, hosts, origins, or tokens do not share state. Server quotas apply account-wide across all of an account's tokens, so coordinate workers on other hosts or other tokens yourself. Python Client instances pace in process unless you pass shared_pacer(base_url, token).

Shared pacing cuts collisions. It does not guarantee that requests dodge throttling. For how the shared file works, see How shared pacing and deadlines work. For the pacing numbers and rate-limit scopes, see Pacing and deadlines.

Use trusted bulk read pacing

Default read spacing is 0.55 seconds. A maintainer can grant your account the submissions.bulk_submit_catalogsubmission permission. With that permission, set OAG_READ_SPACING=0.11 for the CLI, or pass read_spacing=0.11 to shared_pacer(base_url, token, ...). That targets about 545 reads per minute under the server's default 600-per-minute trusted read quota (BULK_AUTHENTICATED_READ_RATE).

Coordinate workers on one host with the same spacing, the same token, and the same OAG_PACING_DIR. Keep status reads batched through watch. Separate tokens for one account share the quota but need caller-managed coordination. Restore 0.55 seconds after a revocation. The server checks the permission on each request, and clients keep honoring shared Retry-After cooldowns.

Faster reads do not change the write pace. See Pacing and deadlines for the write minimums.

Reference

Command synopsis

oag --version
oag products list
oag products list --search "code review"
oag products list --has-mcp --tier A --category code-generation
oag products list --page-size 50 --all
oag products get <slug> --expand mcp_servers,api_specs
oag products filters --output json
oag organizations list --search anthropic
oag organizations get <slug>
oag people get <slug>
oag get "https://www.openagentguide.com/api/v1/catalog/products/?cursor=..."
oag coverage <slug> --output json
oag validate batch.json --output json
cat batch.json | oag validate - --output jsonl
oag submit batch.json --journal batch.journal.json --output json
oag status 00000000-0000-0000-0000-000000000001 --output json
oag status 00000000-0000-0000-0000-000000000001 --output explain
oag watch --file ids.txt --journal watch.journal.json --timeout 900 --output jsonl
oag watch 00000000-0000-0000-0000-000000000001 --journal watch-one.json
oag retire 00000000-0000-0000-0000-000000000001 --force --reason "stale"
oag retire 00000000-0000-0000-0000-000000000001 --force --successor UUID --output json
oag source-preview https://example.com/pricing --claim "Free tier exists"
oag source-preview https://example.com/openapi.json --api-spec --output json

oag --version (-V) prints the installed version and exits 0.

products

products list lists products. products get PRODUCT reads one product by slug or UUID.

• --search TEXT runs a free-text search.
• --category SLUG, --organization SLUG, and --tier TIER filter the list. Repeat any of them for OR matching.
• --has-mcp and --no-has-mcp filter on MCP presence.
• --filter KEY=VALUE passes any other server filter. Repeat for more. Run products filters to list every accepted filter.
• --expand RELATIONS includes related records, comma-separated. --fields FIELDS selects top-level fields, comma-separated.
• --page-size N sets the page size. --cursor TOKEN reads one page from a cursor. --all follows every next link and prints one JSON array of all rows.

products filters lists every filter the list command accepts. It reads the live OpenAPI document and prints each filter's name, type, description, and allowed values. --output json returns the same contract as a machine-readable object. organizations filters and people filters do the same for their list commands.

A single-page read prints the server envelope. --all prints a JSON array of the result rows. Catalog reads work anonymously. A failed read exits 3 with the server's sanitized envelope on stderr.

organizations

organizations list lists organizations; --search matches names, slugs, and URLs. organizations get ORGANIZATION reads one organization by slug or UUID. Both commands take --expand, --fields, --page-size, --cursor, and --all with the same meaning as products.

List responses use cursor pagination. The CursorPageSchema envelope holds count, results, next, previous, page_size_default, and page_size_max. Follow the absolute next link until it is null, or pass --all.

people

A person publishes a product in place of an organization. people list lists people; the list endpoint has no free-text search, so --name matches an exact name and --filter slug=... or --filter affiliation_id=... applies the other filters. people get PERSON reads one person by slug or UUID. Both commands take --expand, --fields, --page-size, --cursor, and --all with the same meaning as products. Most readers reach a person through products get <slug> --expand person instead.

get

get PATH is the escape hatch for a read the named commands do not cover: a pagination next link, or a submissions read-API path. It prints the server body as JSON on one line. PATH is a relative read-API path or a same-origin absolute URL, so a next link passes straight back without stripping its origin. The client accepts an absolute PATH only when its scheme and host match OAG_BASE_URL with no userinfo. A foreign origin, userinfo, an unsupported scheme, or a path outside the catalog or submissions read API exits 2 without a request. Catalog reads work anonymously. The submissions field contract needs OAG_TOKEN.

coverage

coverage PRODUCT reads one product's coverage gaps and its unknown scored fields. It calls GET /api/v1/catalog/products/<slug-or-uuid>/coverage/. The default text output adds evidence guidance for each gap. --output json prints one compact report. coverage reads anonymously. A failed read exits 3 and wraps the server error in a {"version": 1, "error": {...}} envelope.

source-preview

source-preview URL previews the verifier's selected evidence for one source before you spend a submission. It runs one paced, authenticated POST; the server runs the verifier's fetch ladder and returns the selected text, snapshot hashes and lengths, completeness, a source-change comparison and failure diagnostics. The client never fetches the URL itself. Repeat --claim for up to 20 claims and pass the same claims and source mode you will submit so the selection matches; --complete-source previews an absence source as a whole and --api-spec a declared API specification. --expected-source-sha256 reports whether the source changed since an earlier preview. JSON/JSONL print the server report unchanged; text prints a concise view. A successful preview exits 0; an endpoint failure (including a preview quota 429) exits 3 with the shared failure envelope; input or configuration errors exit 2. Preview needs OAG_TOKEN, never corroborates a claim or authorizes publication, and warms the server's one-hour fetch cache, so submitting the same URL within the hour reuses the fetch instead of re-paying.

validate and submit

validate and submit take one JSON object or an array. The input comes from a file or from - for stdin. Nested relation envelopes and explicit nulls pass through unchanged. Omitted keys stay omitted. Validation calls the server and returns its field-path errors. It does not probe external citation URLs. The batch preflight script still covers that separate check.

status and watch

status fetches one submission with all its checks and reviews pages. watch polls unresolved IDs in batches of up to 100 (ids=...&page_size=100&fields=id,status,review_ready,check_feedback,guidance). Pending records hold that compact snapshot. When an ID goes terminal, watch fetches its full detail and every checks and reviews page. Watch keeps claim verdicts, rationales, citations, and resolution reasons.

The lifecycle maps to a terminal status:

• Only lifecycle merged counts as accepted.
• An ordinary closed is rejected.
• A closed proposal with a retirement disposition reports withdrawn or superseded. Replacement IDs appear in resolution.closed.successor_ids.
• A check error on an open submission stays pending.
• A failed detail read or evidence read becomes failed-to-read, even after a terminal lifecycle was seen. Missing batch IDs stay failed-to-read too.

Watch retries unresolved records in later rounds. It stops revisiting a terminal record only after it captures the record's evidence. The journal keeps those terminal snapshots across restarts. Start a fresh journal for a fresh view of later evidence. The server must support the ids filter.

retire

retire withdraws or supersedes one of your open submissions:

• With no --successor option it withdraws the proposal.
• One or more --successor UUID options supersede it with those explicit newer replacements.
• --reason TEXT records an optional reason.

retire makes one request and never retries. --force is required; without it retire refuses, sends nothing, and exits 2. The tool never withdraws or supersedes on your behalf. The server enforces author-or-curator permission and newer-only successors. A success reports the server's disposition (withdrawn or superseded) and exits 0. A 403 or a validation error exits 3. The command does not poll afterward. Use status or watch to follow the retired submission and its successors.

Reading guidance

status and watch request guidance and keep its next_action code. For direct API reads, request guidance alongside status, resolution, and check_feedback. The codes:

• wait: keep watching.
• prepare_correction: prepare the repair now, but wait for terminal closure before you submit it.
• revise_and_resubmit: inspect the rejection, correct the proposal, then validate against the current catalog.
• none: read the terminal resolution, including any successor links.

Guidance never reserves an identity. Guidance never bypasses create conflicts. If guidance is absent, fall back to lifecycle status. Never infer rejection from a check error. Preserve your submit and watch journals.

Output formats

Every command takes --output text|json|jsonl|explain. JSON holds version, records, and summary. JSONL emits one type: record line per result, then a type: summary line. Output lands at completion, including watch cancellation. Watch also emits changed next-action guidance to stderr as it runs. Text prints the full record with indented evidence. Then text lists any check feedback and absence-attestation guidance, one scannable line each. You see why a row needs work without digging through the JSON. Diagnostics go to stderr. No command prompts.

A failed read keeps the server's structured error. Every failed-to-read record carries a failure object with a kind. The kind is http, deadline, transport, or client. An http failure also carries http_status, plus the server's code, detail, and validation errors when present. The human-readable error string stays too. coverage wraps the same object in a {"version": 1, "error": {...}} envelope on failure and exits 3. Its successful report is unchanged.

Exit codes

Exit	Meaning
0	Validation/submission succeeded, or all watched records are terminal
2	Invalid arguments, configuration, input, or journal
3	At least one failed/ambiguous batch row or failed-to-read record
4	Pending records remain at the deadline or in one-shot status
5	All records were read, but --require-all-merged found a rejection
130	Cancelled by Ctrl-C

Failures outrank pending records. Pending records outrank --require-all-merged. By default a fully read rejection exits 0, because watching finished. Pass --require-all-merged to status or watch to require acceptance. Summaries always separate accepted, rejected, pending, and failed-to-read. Batch summaries also count valid, created, failed, and ambiguous rows.

Pacing and deadlines

--timeout is an overall seconds budget. It is 300 for validate and submit, 60 for status, and 900 for watch. It covers pacing waits, requests, retries, and cooldowns. Watch pauses 15 seconds between rounds. Ctrl-C ends watch with a final summary and exit 130. Its journal can resume. A hard kill cannot emit a summary.

The client spaces reads 0.55 seconds apart and mutations 3.5 seconds apart. Validation POSTs use the mutation pace. Requests have a 45-second budget, capped by the remaining workflow deadline. Validation and keyed creates retry transport failures, 5xx, and transient 429s, up to five attempts. Unkeyed writes retry only transient 429s. Polling makes one attempt per round.

Future mutation reservations leave the read schedule unchanged. Create and validate use the mutation lane. Globally throttled writes such as review, merge, close, and retire share the read lane and keep a 0.55-second minimum even when reads run faster. If a peer extends Retry-After during a wait, the worker reserves a fresh slot to keep spacing after the cooldown. Cancelled or expired reservations stay on their lane until their slots pass. Restart preserves them. Custom Pacer.reserve implementations must accept global_mutation=False.

The rate-limit scopes are global_auth for reads, and submission and submission_burst for submission mutations. Workers that do not use the client's shared pacing must pause every worker on the exhausted X-RateLimit-Scope for at least its Retry-After seconds, with jitter, before they resume.

Sizing batches

Size batches against the combined workload. Fifty validation POSTs followed by fifty create POSTs need about 350 seconds of mutation spacing alone, before network time, retries, cooldowns, or other workers' reservations. Those are separate command budgets. Raise --timeout per command for its share of the work. Leave extra time for watch to capture terminal evidence. More concurrent processes do not raise shared throughput. Prefer smaller batches, fewer simultaneous validators and submitters, and one watcher per account that holds all unresolved IDs. Use one pacing directory for concurrent validate, submit, and watch commands.

Environment variables

• OAG_TOKEN: the bearer token. Generate one in your account settings. Catalog reads work without it. The submissions field contract needs it.
• OAG_BASE_URL: the API origin. It defaults to https://www.openagentguide.com. It cannot contain credentials, a path, a query, or a fragment.
• OAG_PACING_DIR: the pacing directory. It defaults to oag-client-pace under the system temp directory. Cooperating processes must share it.
• OAG_READ_SPACING: the read spacing in seconds. The default is 0.55. Set it to 0.11 with the submissions.bulk_submit_catalogsubmission permission.

Python API

from oag_client import Client, shared_pacer
from oag_client.transport import HTTPTransport
from oag_client.workflows import payloads, validate

base_url = "https://www.openagentguide.com"
# Omit `pacer` for in-process pacing; pass `shared_pacer` to coordinate with
# other processes on this host that share the token.
client = Client(HTTPTransport(token), base_url, pacer=shared_pacer(base_url, token))
records = validate(client, payloads(json_text), deadline=client.clock.monotonic() + 60)

submit, status, watch, summary, and exit_code also come from oag_client.workflows. Journal lives in oag_client.journal. The Clock and Transport protocols make testing deterministic. A custom transport must accept the optional idempotency_key keyword and forward it as Idempotency-Key on create requests. The HTTP transport is synchronous, so async callers should use a worker thread. Application code supplies authorization. Pacing is in process by default. Pass shared_pacer(base_url, token) (or any Pacer) to coordinate processes that share a directory, an origin, and a token on one host. Coordinate other tokens or hosts yourself, because server quotas cover the whole account.

Explanation

How journals and idempotency keys keep submissions safe to retry

Always reuse the same submit journal for a batch. The journal binds the ordered input hash, the base URL, and the token fingerprint. Changed inputs, environments, or tokens fail instead of replaying. The journal never stores tokens. The journal holds server evidence and may hold private submission data, so keep it private.

Each new row gets a random UUID Idempotency-Key. The client flushes the key to the journal before the first POST. Every attempt and restart reuses that key and the same input. A confirmed 201 records the original submission ID as created, even if the server already merged or closed it. The client skips confirmed and definitively failed rows on restart. Keyed ambiguous or pending rows retry within the command's deadline. Exhausted transient failures stay unresolved.

Journal writes are atomic and flushed to disk. A lock prevents simultaneous writers. After a hard kill, confirm that no writer remains before you delete the .lock file. Never delete a journal to recover from a timeout. Never change a journal's keys to recover from a timeout. A deadline or cancellation after an uncertain attempt preserves its key.

The client uses semantic versioning. JSON output stays version 1. New and saved journals use version 2. Version-1 journals stay readable, but unkeyed uncertain rows need manual reconciliation. Older clients reject version-2 journals. An upgrade alone never sends requests and never rewrites journals. Running submit resumes keyed uncertain rows. Pair the client with a server that supports the create Idempotency-Key contract.

How shared pacing and deadlines work

The client spaces reads and mutations to stay under the server's quotas. The oag CLI shares reservations and Retry-After cooldowns across processes on one host when the processes use the same pacing directory, API origin, and token. The filename hashes the origin and a one-way token fingerprint, so separate directories, hosts, origins, or tokens do not share state. The file stores timestamps, never the raw token. A crash releases the file lock but keeps its recorded reservations, so a restart preserves them.

A transient 429 extends the shared cooldown to the longest value that any cooperating process reports. The client honors numeric and HTTP-date Retry-After values within the workflow deadline, across reads and mutations together.

Shared pacing cuts collisions. It does not guarantee that requests dodge throttling. Server quotas apply account-wide across all of an account's tokens, so coordinate separate tokens and separate hosts yourself. More concurrent processes do not raise shared throughput. The open-submission-cap 429 returns immediately without a retry.

A watch timeout does not mean a submission failed. Resume the journal and inspect the lifecycle and the terminal evidence. The journal and the idempotency keys make an uncertain create safe to retry without a duplicate.