Skip to content

Getting started with the CLI, REST and registry tools

This page is for the Argus CLI, REST and the registry tools, which keep their own contracts. To connect an AI app such as Claude and use the consumer tools, follow the quickstart.

1. Choose an interface

Sign in with interactive OAuth. Argus does not issue machine API keys to the public. For private research, subscriptions, usage and exports through registry tools, follow the personal-service examples. Published Skills describe the interfaces; they do not imply approval of an untested hosted platform.

Interface Use it when Authentication Result
CLI A shell-based AI agent needs JSON on stdout Registered OAuth-backed session CliToolEnvelope for financial tools; typed personal result for personal tools
REST A service already uses HTTP/JSON API session / OAuth Bearer; approved machine API key for compatible fact tools Same per-tool JSON contracts
MCP An MCP client discovers and invokes tools OAuth against the MCP resource consumer-result-v1 for the listed consumer tools; earlier registry tools keep their contracts

All three interfaces enter the same CoreServiceBoundary with permission, tool-whitelist, tenant, license, output-policy, and audit checks. OAuth does not bypass this chain. License enforcement follows the configured runtime switches; ordinary fact reads default to recording generic license decisions without blocking. Additional source-use checks remain active for composed personal facts, display, bookmarks, storage, notifications, export and external-model processing. The CLI's signed argus:tools:public scope grants everyday fact tools. Advanced research and diagnostics need explicit signed grants and the required data scopes. Registry discovery is public. Check the required signed scopes and the permission_requirements.default_oauth_access metadata before calling a tool.

2. Install the CLI and sign in

Install the official CLI from the API host. On Linux or macOS:

curl -fsSL https://api.argusfa.com/install | bash

In Windows PowerShell:

irm https://api.argusfa.com/windows/install | iex

The website's Developers page also links the install scripts and the Skill packages. Then sign in:

argus auth login
argus auth status

The CLI uses Authorization Code + PKCE S256 and the operating-system credential store. It never stores a client secret.

3. Discover tools before calling one

The public registry requires no tool execution and describes every supported binding, parameter, permission scope, return contract, prohibited capability, safe alternative, and deprecation state.

curl -fsS https://api.argusfa.com/v1/tool-registry

The registry covers the CLI, REST and the earlier MCP tools. On the OAuth MCP endpoint, tools/list shows the consumer tools instead. The registry tools, including agent_tool_registry, are neither listed nor callable there; use the CLI or REST for them. See consumer tool discovery.

Start with company_fact_snapshot for disclosed facts, filing_search for cited filing fragments, or agent_data_preflight when the requested fields, time range, license, or permission status is uncertain. agent_data_preflight is a diagnostics tool and needs an explicit signed grant.

4. Make a first registry request

argus --base-url https://api.argusfa.com entity-resolve   --identifier-type ticker   --identifier-value AAPL   --purpose factual_lookup

The CLI reads the opaque registered session stored in step 2; upstream credentials stay in the trusted identity component. Use argus auth refresh when refreshing the registered upstream chain is required. This request uses the current query time; historical requests require an aware ISO-8601 timestamp within verified coverage. Z means UTC. Unknown request fields are rejected instead of ignored.

Inspect the returned facts, coverage and evidence, then carry the returned permanent identifiers into the appropriate downstream tool. A ticker, a CIK and a security ID are different identifier types; do not use one in place of another. agent_data_preflight verifies target data only for its supported probes, using the company or security IDs accepted by each target. Other targets report target_query_arguments_not_verified; inspect their actual results and evidence instead of treating preflight as an availability guarantee. Empty, partial and unavailable results remain coverage gaps.

Registry discovery proves that an invocation contract exists, not that its production data source has been verified for every subject. For company discovery use company_master, and inspect each returned coverage code before choosing downstream calls. A value is claimed only when a captured row establishes it at as_of; the original listing date, historical identity, complete target coverage and any field whose capture is missing remain explicit gaps rather than inferences. See PIT coverage and stream coverage.

5. Validate a registry response

Do not treat HTTP 200 alone as proof that data is usable. Validate the envelope and nested package for a legacy financial tool:

success
  -> audit_id
  -> permission_result / license_status
  -> source_evidence
  -> output_restrictions
  -> result.result_status / result.coverage_gaps
  -> result.data_quality
  -> result.known_time <= requested as_of
  -> every fact.evidence_ids entry exists in result.source_evidence

If data_quality.requires_human_review is true, route the package to review. If a license is restricted, preserve its field and redistribution restrictions in all downstream systems.

Personal tools use personal-result-v1 instead of success/result: inspect transport status, problem, payload, audit_id, owner/lifecycle and the per-tool schema. See personal examples. Do not apply the legacy response checklist to private records or assume user notes have external financial evidence.

Consumer tools on /mcp return consumer-result-v1: check status, notes and freshness, and expand citations with get_sources. See consumer-result-v1.

Evidence backed by private storage exposes evidence_lookup_id equal to its evidence_id in place of the internal storage URI. Preserve this opaque reference and source_file_id; use the authorized source_evidence_lookup tool for available evidence metadata. A reference does not grant access to controlled source text or promise a public download URL. Public packages can be parsed back into the DataPackage schema without private storage locators.

6. Handle failures by code

HTTP status Typical meaning Next action
400 Invalid arguments or a legacy policy error Correct the request using the machine-readable details
401 Missing, invalid, expired, or revoked credential; identity mismatch; rate limit Check the credential and its bound identity; rotate if needed
403 Permission, tenant, license, or output-policy denial Do not retry unchanged; request the required scope or change purpose/data
422 Request does not match the strict REST schema Correct field names, types, timestamps, or required values
500 Core operation failed after governance entry Record audit_id, stop blind retries, and report it with the audit_id
503 The service or a required public artifact is unavailable Retry with backoff

Failure bodies are machine-readable. Persist the returned audit_id and error_code; do not parse the human message to drive control flow.

Next steps