From 7d1c60670c58e727c056b6327e56cb5041882c4a Mon Sep 17 00:00:00 2001 From: Hyperion <89154626+daniel-scrivner@users.noreply.github.com> Date: Thu, 16 Jul 2026 10:11:44 -0600 Subject: [PATCH 1/3] docs: clarify CLI quickstart --- README.md | 51 ++++++++++++++------------------------------------- 1 file changed, 14 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 62b85f0..78f0d66 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,38 @@ # SEC API CLI -`@secapi/cli` is the command-line client for SEC API. Use it to retrieve filings, filing sections, statements, entity data, and account information from a terminal or an agent runner. +`@secapi/cli` is the command-line client for retrieving source-backed SEC filings, filing data, and account context from a terminal or agent runner. -[Documentation](https://docs.secapi.ai) · [Get an API key](https://secapi.ai/signup) · [Support](https://secapi.ai/support) · [Status](https://status.secapi.ai) - -## Install and make a request +## Install and retrieve a filing ```bash npm install -g @secapi/cli -export SECAPI_API_KEY="secapi_live_..." +export SECAPI_API_KEY="secapi_..." secapi filings latest --ticker AAPL --form 10-K ``` -The command writes JSON to stdout. The response identifies the filing and includes fields such as its form, filing date, accession number, and SEC source URL. Use `--json=false` in an interactive terminal when a compact human-readable summary is preferable. +The command writes JSON to stdout with the current filing's accession number, filing date, SEC source URL, and request ID. Those live values can change when a newer filing is available. -## Start here +The CLI sends `SECAPI_API_KEY` as `x-api-key` to `https://api.secapi.ai` and calls the public REST contract. For an MCP-compatible client, use the [hosted MCP server](https://docs.secapi.ai/mcp-install); the CLI can generate supported client configuration without storing a key. -```bash -secapi --help -secapi filings latest --help -secapi examples -secapi doctor -``` +## Compatibility and support -`doctor` checks the selected API origin, credential source, API health, and account context without printing credential values. `examples` prints starter workflows. Commands accept `--base-url ` for a one-off local, staging, or proxy origin. +Node.js and npm are required. The preferred executable is `secapi`; `omni-sec` remains a compatibility alias. See the [CLI guide](https://docs.secapi.ai/cli) and [API reference](https://docs.secapi.ai/api-reference), check [status](https://status.secapi.ai), or contact [support](https://secapi.ai/support). -For CI and agent runners, keep credentials out of command arguments. Set `SECAPI_API_KEY`, or pipe a key with `--api-key-stdin`: +## Inspect and configure ```bash -printf '%s' "$SECAPI_API_KEY" | secapi health --api-key-stdin +secapi filings latest --help +secapi doctor +secapi mcp install --client claude-code ``` -## Agent setup - -Configure the hosted MCP server for a supported agent client: +`doctor` checks the selected origin, credential source, API health, and account context without printing credential values. Use `--base-url ` only for an environment you control. For CI and agent runners, keep credentials out of command arguments: set `SECAPI_API_KEY`, or pipe a key with `--api-key-stdin`. ```bash -secapi mcp install --client claude-code -secapi init --client cursor --print -secapi agent-context --output secapi-cli-context.json +printf '%s' "$SECAPI_API_KEY" | secapi health --api-key-stdin ``` -`agent-context` produces a machine-readable command inventory. `--print` shows generated configuration without writing it. Run `secapi init --help` for the current client list. - -## Factor response modes - -Use `--response-mode compact` when you want the smallest useful payload. Compact catalog responses still include readiness/proof summaries. Add `--include trust` only when you need the full trust/provenance envelope plus full methodology/materialization/revision/source-rights objects for citations or checks. For catalog/tool-discovery calls, first narrow with `--category`; `--limit` is available on factor list commands such as `factors extreme-moves`, not `factors catalog`. The full trust envelope can be larger than a simple picker payload. - -## Configuration and compatibility - -The CLI reads `SECAPI_API_KEY`, `SECAPI_BEARER_TOKEN`, and the optional `SECAPI_BASE_URL`. It defaults to `https://api.secapi.ai`. `SECAPI_PROFILE` and `SECAPI_CONFIG_FILE` select a no-secret profile file; profiles store environment-variable names, not credential values. - -The preferred executable is `secapi`. `omni-sec` is installed as a compatibility alias with the same commands. Discover the full surface with `secapi help all`; unknown commands and options fail locally with suggestions. - -## Support - -Run `secapi support bundle` to create a redacted local diagnostics packet for a support handoff. Include its request ID when contacting [SEC API support](https://secapi.ai/support). +`secapi agent-context --output secapi-cli-context.json` writes a machine-readable command inventory. `secapi init --client cursor --print` shows generated client configuration without writing it. Profiles store environment-variable names, not credential values. ## License From 7c7ce32cdd2d50681a64ec479e6e404fb7a23a10 Mon Sep 17 00:00:00 2001 From: Hyperion <89154626+daniel-scrivner@users.noreply.github.com> Date: Sat, 18 Jul 2026 09:13:04 -0600 Subject: [PATCH 2/3] chore: align public package metadata --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index f1b3c33..4dd861c 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@secapi/cli", "version": "1.4.0", - "description": "SEC API CLI for SEC data shaped for investors and agents", + "description": "Command-line client for source-backed SEC filings and financial data", "type": "module", "bin": { "secapi": "dist/index.js", @@ -36,7 +36,7 @@ "mcp" ], "license": "MIT", - "homepage": "https://secapi.ai/developers", + "homepage": "https://docs.secapi.ai", "bugs": { "url": "https://docs.secapi.ai/support" }, From dc0e8dc73884c9248b13338b9f05c991abd56afc Mon Sep 17 00:00:00 2001 From: Hyperion <89154626+daniel-scrivner@users.noreply.github.com> Date: Sat, 18 Jul 2026 09:18:41 -0600 Subject: [PATCH 3/3] chore: fix public support metadata --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 4dd861c..42557bf 100644 --- a/package.json +++ b/package.json @@ -38,7 +38,7 @@ "license": "MIT", "homepage": "https://docs.secapi.ai", "bugs": { - "url": "https://docs.secapi.ai/support" + "url": "https://secapi.ai/support" }, "repository": { "type": "git",