CodeAnt-AI · Sagar-CodeAnt · Aug 26, 2026 · Aug 26, 2026 · Aug 27, 2026
diff --git a/README.md b/README.md
@@ -131,6 +131,40 @@ Show the current API base URL and its source.
 codeant get-base-url
 ```
 
+#### `hotlist`
+
+Query the same organization-wide prioritized findings shown in the CodeAnt Hotlist, or fetch one finding by its stable ID.
+
+```bash
+codeant hotlist list --org CodeAnt-AI --service github --severity critical,high
+codeant hotlist get 0123456789abcdef0123456789abcdef --org CodeAnt-AI --service github
+```
+
+#### `findings`
+
+Access repository, organization Hotlist, cloud-security, anti-pattern, and pentest findings through one command group.
+
+```bash
+codeant findings repos --org CodeAnt-AI
+codeant findings repo --repo CodeAnt-AI/example --types sast,sca,iac,anti_patterns
+codeant findings list --severity critical,high
+codeant findings cloud history --provider all
+codeant findings pentest history
+```
+
+See [findings.md](findings.md) for the complete command and agent manual.
+
+#### `api request`
+
+Call any CodeAnt application API using the saved bearer token. Only relative paths on the configured CodeAnt API host are accepted.
+
+```bash
+codeant api request GET /some/read/endpoint --org CodeAnt-AI --service github --query '{"page":1}'
+codeant api request POST /some/app/endpoint --org CodeAnt-AI --service github --body '{"repo":"CodeAnt-AI/example"}'
+```
+
+See [findings.md](findings.md) for all finding commands and [cli-api.md](cli-api.md) for raw API, authentication, self-hosted provider, and agent/MCP details.
+
 ### Global Options
 
 ```bash
@@ -240,11 +274,11 @@ node src/index.js secrets --all
 
 This package also ships an MCP (Model Context Protocol) server that exposes CodeAnt's scan, review, and PR data as tools to Claude and other MCP clients. The same source tree is packaged as a Desktop Extension (`.mcpb`) for one-click install in Claude Desktop.
 
-See [mcp.md](mcp.md) for the tools listing, install paths (Claude Code CLI, Claude Desktop manual config, MCPB double-click), and bundling/submission instructions.
+See [mcp.md](mcp.md) for the tools listing, install paths (Claude Code CLI, Claude Desktop manual config, MCPB double-click), and bundling/submission instructions. See [cli-api.md](cli-api.md) for Hotlist and generic authenticated API usage.
 
 ## Privacy Policy
 
-Full policy: **https://codeant.ai/privacy**
+Full policy: **https://www.codeant.ai/privacy-policy**
 
 Summary of what this CLI / MCP server sends and stores:
 

diff --git a/cli-api.md b/cli-api.md
@@ -0,0 +1,130 @@
+# CodeAnt application APIs from the CLI
+
+The CLI can call the authenticated application endpoints used by the CodeAnt web app without adding a second backend adapter for each endpoint. Sign in once, select one exact organization/provider connection, then use a first-class command or the generic API request command.
+
+```bash
+codeant login
+codeant scans orgs
+```
+
+`CODEANT_API_TOKEN` and `CODEANT_API_URL` can be used instead of the saved login for agents, CI, and self-hosted installations.
+
+The browser login binds the CLI key to the signed-in user and the exact connections visible to that user. For application API calls, the backend resolves the selected connection and injects the same verified user identity used by the app. The existing organization-membership, RBAC, repository-access, audit, and request guards still run. CLI keys expire after 90 days by default (`CLI_API_KEY_TTL_DAYS` controls the backend deployment value), and `codeant logout` revokes the key server-side before deleting it locally.
+
+Keys created before this authenticated application-API bridge do not contain the verified user identity. Run `codeant logout` followed by `codeant login` once after upgrading.
+
+## Hotlist findings
+
+Hotlist commands use the same organization-wide snapshot, ranking, filters, stable finding IDs, and cursor pagination as the app.
+
+```bash
+# First page; org/service are auto-selected when unambiguous
+codeant hotlist list
+
+# Highest-priority production findings for one authenticated connection
+codeant hotlist list \
+  --org CodeAnt-AI \
+  --service github \
+  --severity critical,high \
+  --validation exploit_confirmed \
+  --limit 50
+
+# Fetch every SCA finding across the organization
+codeant hotlist list --org CodeAnt-AI --service github --type SCA --all
+
+# Continue a page using next_cursor from the previous response
+codeant hotlist list --org CodeAnt-AI --service github --cursor '<cursor>'
+
+# Fetch exactly one finding using the stable ID shown in the app
+codeant hotlist get 0123456789abcdef0123456789abcdef \
+  --org CodeAnt-AI \
+  --service github
+```
+
+Supported `hotlist list` filters:
+
+| Option | Values |
+|---|---|
+| `--search` | title, repository/account, path, package, CVE, or check ID |
+| `--type` | `AI Exploitation`, `SCA`, `SAST`, `Secrets`, `IaC`, `Infrastructure` |
+| `--location` | repository full names or cloud accounts |
+| `--severity` | `critical`, `high`, `medium`, `low`, `unknown` |
+| `--ticket-status` | `created`, `not_created` |
+| `--compliance` | framework keys such as `soc2` |
+| `--validation` | `exploit_confirmed` |
+
+Comma-separated values are accepted. The default page size is 30 and the maximum is 100. `--all` follows every cursor. If the first organization snapshot is still being built, the command waits up to 60 seconds; change that with `--max-wait <seconds>`.
+
+For self-hosted GitHub, GitLab, Bitbucket, or Azure DevOps, the CLI normally discovers the provider base URL from the authenticated connection. Use `--provider-base-url` only to override it.
+
+## All findings
+
+Use `codeant findings` for first-class access to repository findings, organization Hotlist and anti-pattern findings, AWS/Azure/GCP cloud-security findings, and pentest engagements. The full command matrix, provider-specific fields, examples, and agent workflow are documented in [findings.md](findings.md).
+
+## Any app API
+
+Use the generic request command when a first-class command does not exist yet:
+
+```bash
+codeant api request GET /some/read/endpoint \
+  --org CodeAnt-AI --service github \
+  --query '{"page":1}'
+
+codeant api request POST /some/app/endpoint \
+  --org CodeAnt-AI --service github \
+  --body '{"repo":"CodeAnt-AI/example"}'
+
+codeant api request PATCH /some/app/endpoint \
+  --org CodeAnt-AI --service github \
+  --body-file ./request.json \
+  --header 'If-Match: revision-123'
+```
+
+The output is JSON:
+
+```json
+{
+  "ok": true,
+  "status": 200,
+  "tenant": {
+    "org": "CodeAnt-AI",
+    "service": "github"
+  },
+  "data": {}
+}
+```
+
+Security properties:
+
+- The path must start with `/` and is always resolved against the configured CodeAnt API host. Absolute and protocol-relative URLs are rejected, so the bearer token cannot be forwarded to another host.
+- Authentication is supplied from `CODEANT_API_TOKEN` or the key saved by `codeant login`.
+- `--org`, `--service`, and the discovered provider base URL must match one saved login connection exactly. They are auto-selected only when unambiguous. Use `--provider-base-url` for a self-hosted override.
+- POST/PUT/PATCH/DELETE bodies must be JSON objects. The CLI adds the selected tenant fields before sending the request; conflicting tenant values are rejected by the backend.
+- `Authorization`, `Cookie`, `Host`, `Content-Length`, and the `X-CodeAnt-CLI-*` tenant headers cannot be overridden.
+- The backend remains authoritative for account access, organization membership, RBAC, and endpoint authorization.
+
+The generic command can call write endpoints. Review the method, path, and body before running it.
+
+## Agent and MCP access
+
+Run `codeant mcp` or install the CodeAnt MCP bundle. Agents receive dedicated read-only tools:
+
+- `codeant_hotlist_list` — filter and page through organization-wide findings.
+- `codeant_hotlist_get` — fetch one finding by stable ID.
+- `codeant_api_get` — authenticated GET access for newly-added read APIs.
+- `codeant_findings_antipatterns` — selected or all-repository anti-pattern findings.
+- `codeant_cloud_scan_history`, `codeant_cloud_findings_list`, `codeant_cloud_finding_get` — cloud scan discovery, findings, and detail.
+- `codeant_pentest_history`, `codeant_pentest_issues`, `codeant_pentest_report` — pentest engagement discovery and results.
+
+Set `CODEANT_READ_ONLY=0` to opt in to write tools, including `codeant_api_request` for POST/PUT/PATCH/DELETE. Read-only mode is the default. The MCP server never opens a browser during startup; the agent must explicitly call `codeant_login` when no token is configured.
+
+## Troubleshooting
+
+| Error | Resolution |
+|---|---|
+| No matching organization | Run `codeant scans orgs`, then pass its exact `organizationName` and `service`. |
+| Multiple organizations match | Pass both `--org` and `--service`. |
+| Access denied (403) | Run `codeant logout`, then `codeant login`, or replace `CODEANT_API_TOKEN`. |
+| Invalid token after upgrading | Older keys lack verified CLI identity metadata. Run `codeant logout`, then `codeant login`. |
+| Hotlist is still building | Retry, or increase `--max-wait`. |
+| Finding not found | Refresh the app/Hotlist and copy the current stable finding ID and tenant context. |
diff --git a/findings.md b/findings.md
@@ -0,0 +1,163 @@
+# CodeAnt findings CLI
+
+`codeant findings` is the unified, read-only entry point for findings visible in the CodeAnt app. It reuses the same authenticated backend endpoints and authorization checks as the UI.
+
+```bash
+codeant login
+codeant scans orgs
+codeant findings --help
+```
+
+When one login has multiple connections, pass the exact `--org` and `--service` values returned by `codeant scans orgs`. A self-hosted provider base URL is discovered from the selected connection; use `--provider-base-url` only as an explicit override.
+
+## Coverage
+
+| App data | CLI command | Scope |
+|---|---|---|
+| Repository list | `codeant findings repos` | organization |
+| SAST, SCA, IaC, Secrets, SBOM | `codeant findings repo` | repository + scan/branch |
+| Anti-patterns, dead code, docstrings, complex functions | `codeant findings repo` | repository + scan/branch |
+| Prioritized SAST/SCA/IaC/Secrets/Infrastructure/AI Exploitation | `codeant findings list/get` | organization Hotlist |
+| Anti-patterns across repositories | `codeant findings antipatterns` | selected repos or organization |
+| AWS/Azure/GCP CSPM, VM, and container findings | `codeant findings cloud history/list/get` | organization + cloud resource scope |
+| Pentest engagements, issues, reports | `codeant findings pentest history/issues/report` | organization + engagement |
+
+The existing `codeant scans repos`, `codeant scans results`, and `codeant hotlist list/get` commands remain supported. The unified commands are aliases or thin authenticated clients, so existing scripts do not need to migrate.
+
+## Repository list and repo-level findings
+
+```bash
+# List connected repositories
+codeant findings repos --org CodeAnt-AI
+
+# Latest scan, all supported finding types
+codeant findings repo --repo CodeAnt-AI/example --types all
+
+# Selected categories and severities
+codeant findings repo \
+  --repo CodeAnt-AI/example \
+  --branch main \
+  --types sast,sca,iac,anti_patterns \
+  --severity critical,high
+
+# A specific scan, formatted for another tool
+codeant findings repo \
+  --repo CodeAnt-AI/example \
+  --scan 0123456789abcdef \
+  --types sast,secrets \
+  --format sarif \
+  --output codeant.sarif
+```
+
+Supported repo types are `sast`, `sca`, `secrets`, `iac`, `dead_code`, `sbom`, `anti_patterns`, `docstring`, and `complex_functions`. Use `--types all` for all of them. Formats are `json`, `sarif`, `csv`, `md`, and `table`; JSON is the default.
+
+Use `--filter-dismissed` to exclude dismissed findings and `--no-false-positives` to exclude false positives. `--path`, `--check`, `--limit`, and `--offset` support agent-friendly filtering and pagination.
+
+## Organization Hotlist findings
+
+`findings list/get` exposes the same stable IDs, prioritization, filters, and cursor pagination as the app Hotlist.
+
+```bash
+codeant findings list --org CodeAnt-AI --service github --severity critical,high
+codeant findings list --type SCA,IaC --location CodeAnt-AI/example --all
+codeant findings get 0123456789abcdef0123456789abcdef --org CodeAnt-AI --service github
+```
+
+Hotlist types are `SAST`, `SCA`, `Secrets`, `IaC`, `Infrastructure`, and `AI Exploitation`. The last two cover prioritized cloud-security and pentest findings. Use the dedicated cloud and pentest commands below when complete scan/engagement data is required.
+
+## Organization anti-patterns
+
+```bash
+# Every repository in the selected organization
+codeant findings antipatterns --org CodeAnt-AI --service github
+
+# Only selected repositories
+codeant findings antipatterns \
+  --org CodeAnt-AI --service github \
+  --repos CodeAnt-AI/api,CodeAnt-AI/web
+```
+
+When `--repos` is omitted, the CLI first lists the organization's repositories and sends all of them to the same aggregate anti-pattern endpoint used by the Quality Report UI.
+
+## Cloud security findings
+
+Cloud findings are organization/account scoped rather than repository scoped.
+
+```bash
+# History across AWS, Azure, and GCP
+codeant findings cloud history --org CodeAnt-AI --service github
+
+# Latest scan per provider
+codeant findings cloud history --provider all --latest
+
+# VM and container vulnerability scan histories
+codeant findings cloud history --provider all --kind vm
+codeant findings cloud history --provider all --kind container
+
+# AWS findings and one full detail record
+codeant findings cloud list --provider aws --scan-id <scan-id> --account-id <account-id>
+codeant findings cloud get --provider aws --scan-id <scan-id> --uid <finding-uid> --cloud-service iam
+
+# VM and container vulnerabilities use the same list/detail flow
+codeant findings cloud list --provider aws --kind vm --scan-id <scan-id>
+codeant findings cloud get --provider gcp --kind container --scan-id <scan-id> --uid <finding-uid>
+
+# Azure requires the tenant ID
+codeant findings cloud list \
+  --provider azure --tenant-id <tenant-id> --scan-id <scan-id> \
+  --severity high --subscription-id <subscription-id>
+
+# GCP requires the project ID
+codeant findings cloud list \
+  --provider gcp --project-id <project-id> --scan-id <scan-id> \
+  --framework cis
+```
+
+`--kind` defaults to `cspm`; use `vm` or `container` for the other Cloud Security result views. CSPM `cloud list` supports `--cloud-service`, `--severity`, `--status`, `--framework`, and `--min-days-unused`. AWS additionally supports `--exploit-attempted-only`; Azure additionally supports `--subscription-id`. CSPM responses include `findings` and `dismissed_findings`; VM/container responses preserve their UI result payload unchanged.
+
+## Pentest findings
+
+```bash
+# Discover engagement IDs
+codeant findings pentest history --org CodeAnt-AI --service github
+
+# All available open issues for an engagement
+codeant findings pentest issues --report-id <report-id>
+
+# Full customer report
+codeant findings pentest report --report-id <report-id>
+
+# Test-environment variant
+codeant findings pentest issues --report-id <report-id> --variant test
+codeant findings pentest report --report-id <report-id> --variant test
+```
+
+`--variant prod` is the default. Pentest entitlements and critical/high redaction are enforced by the backend exactly as they are in the UI; the CLI does not bypass locked content.
+
+## Agent/MCP tools
+
+Agents can use these read-only MCP tools:
+
+| Tool | Purpose |
+|---|---|
+| `codeant_scans_repos` | List repositories. |
+| `codeant_scans_results` | Fetch repo-level SAST/SCA/IaC/Secrets/quality findings. |
+| `codeant_hotlist_list`, `codeant_hotlist_get` | Query prioritized org-wide findings and stable IDs. |
+| `codeant_findings_antipatterns` | Fetch selected or all-repo anti-pattern findings. |
+| `codeant_cloud_scan_history` | Discover AWS/Azure/GCP scan IDs and scopes. |
+| `codeant_cloud_findings_list`, `codeant_cloud_finding_get` | List cloud findings and retrieve full detail. |
+| `codeant_pentest_history`, `codeant_pentest_issues`, `codeant_pentest_report` | Discover and inspect pentest engagements. |
+
+All these tools are available in the default read-only MCP mode. A typical agent flow is discovery (`orgs` -> `repos`, cloud history, or pentest history), list/filter findings, then retrieve one detailed finding or report.
+
+## Errors and access
+
+| Error | Resolution |
+|---|---|
+| No or multiple matching organizations | Run `codeant scans orgs`; pass exact `--org` and `--service`. |
+| Access denied (403) | Run `codeant logout`, then `codeant login`. Older CLI keys must be refreshed once. |
+| Missing Azure/GCP scope | Pass `--tenant-id` for Azure or `--project-id` for GCP. |
+| Report or scan not found | Use the corresponding history command and verify the selected tenant/provider. |
+| Redacted pentest fields | Unlock the engagement in the app; CLI access follows the same entitlement. |
+
+For the generic authenticated API escape hatch and authentication details, see [cli-api.md](cli-api.md).