finterm CLI - Finterm

The Finterm CLI (@finterm-ai/cli package, finterm command) provides authenticated financial data lookups, company web research bundle runs, agent documentation, local Dataroom reading, and a built-in feedback channel to the Finterm team. Finterm is designed to drop into a coding agent: the agent operates the CLI on the user’s behalf, translating natural requests (“what’s NVDA trading at?”, “diff META’s risk factors”) into finterm commands and presenting the results; finterm setup installs the agent skill and finterm skill / finterm prime load the workflow. Everything here also works directly from a terminal for users who prefer that.

Installation

Run without installing:

npx @finterm-ai/cli@latest --help

Or install globally so the finterm command is always available:

npm install -g @finterm-ai/cli

Finterm requires Node.js 22.12 or newer.

Quick Start

finterm --help          # Show all commands
finterm auth status     # Check token state
finterm auth login      # Authenticate when needed
finterm setup --check   # Verify agent setup
finterm setup           # Install supported agent setup
finterm skill --brief   # Short agent workflow
finterm tool --help     # Public point-tool surface
finterm bundle run company_deep_research AAPL \
  --param q=Q1 --param fy=2025 --param prev_q=Q4 --param prev_fy=2024
finterm feedback --help # Report a bug, ask a question, request a feature

Commands

For option-level detail, run finterm <command> --help or finterm <command> <subcommand> --help.

Documentation Commands

`finterm docs`

Shows this full documentation. Output is automatically paged when running interactively.

`finterm prime`

Shows compact context for AI coding agents. Use it after context compaction or at the start of a new session.

`finterm skill`

Outputs the full agent skill. Options:

--brief - Output condensed workflow rules instead of the full skill file

`finterm shortcut [query]`

Find and output reusable agent shortcuts. Use --list to list available shortcuts.

`finterm resources [query]`

Find and output reference resources. Use --list to list available resources.

Initialization Commands

`finterm init`

Initializes Finterm in the current directory by creating .finterm/config.yml. Creates:

.finterm/config.yml - Configuration file
.finterm/.gitignore - Ignores local-only files

Use finterm setup for agent integration.

Authentication Commands

Authenticate with the Finterm platform. Signing in creates a new account API key and revokes the previous active key. The command opens the browser by default and always prints the login URL as a fallback for copy and paste. Options:

--no-browser - Print the login URL without opening a browser
--device-name <name> - Set the display name for the CLI device

Use FINTERM_API_KEY instead of finterm auth login for fully non-interactive automation.

`finterm auth status`

Check the active authentication source, token id, masked key, and plan/trial state. Data and tool calls require Finterm Pro; finterm auth status and finterm feedback work with any authenticated key.

`finterm auth logout`

Remove the stored local authentication token.

Setup Commands

`finterm setup`

Installs the Finterm agent skill once into supported agent locations. The command is idempotent and non-interactive. Options:

--check - Show setup status without changing anything
--remove - Remove installed agent setup

Point Tool Commands

finterm tool <id> exposes authenticated point-data lookups. Use finterm tool --help and finterm tool <id> --help before adding flags. Add --json for machine-readable output.

Tool Command Reference

These command options come from the shipped CLI command spec; summaries are checked against the public .api.md definitions.

`finterm tool financial_statements`

Reported balance sheet, income statement, or cash flow for a company.

Argument	Required	Description
`ticker`	yes	Stock ticker (e.g., AAPL)

Option	Required	Choices / Default	Description
`--statement-type \<type>`	yes	choices: balance_sheet, income_statement, cash_flow	Statement type (required)
`--as-of-date \<date>`	no	none	Filing/resource as-of date, YYYY-MM-DD (default: today)
`--timeframe \<timeframe>`	no	choices: quarterly, annual, trailing_twelve_months; default: annual	Timeframe
`--limit \<number>`	no	default: 4	Number of periods to return
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm tool options_sentiment`

Put/call options sentiment for a symbol on a specific date, with a sample-quality verdict.

Argument	Required	Description
`ticker`	yes	Underlying stock ticker (e.g., AAPL)

Option	Required	Choices / Default	Description
`--as-of-date \<date>`	no	none	Date for analysis, YYYY-MM-DD (default: today)
`--include-spread-analysis`	no	default: false	Include spread analysis
`--expiration-filter \<filter>`	no	none	Filter by expiration window
`--max-contracts \<number>`	no	default: 50	Maximum contracts to analyze
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm tool sec_filings_search`

Search SEC EDGAR filings for a company by ticker and form type.

Argument	Required	Description
`ticker`	yes	Stock ticker (e.g., AAPL)

Option	Required	Choices / Default	Description
`--form-type \<type>`	no	choices: 10-K, 10-Q, all; default: all	Filter by form type
`--as-of-date \<date>`	no	none	Only filings after this date (YYYY-MM-DD)
`--limit \<number>`	no	default: 10	Maximum filings to return
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm tool sec_filing_fetch`

Fetch narrative sections from a company’s SEC filing by fiscal year and period.

Argument	Required	Description
`ticker`	yes	Stock ticker (e.g., AAPL)

Option	Required	Choices / Default	Description
`--year \<year>`	yes	none	Fiscal year (e.g., 2024) (required)
`--period \<period>`	yes	choices: FY, Q1, Q2, Q3, Q4	Fiscal period (required)
`--sections \<sections>`	no	default: risk_factors	Comma-separated section names (e.g., risk_factors,business)
`--format \<format>`	no	choices: text, json, yaml; default: text	Output format

`finterm tool sec_filing_diff`

Compare two of a company’s SEC filings and report section-level changes.

Argument	Required	Description
`ticker`	yes	Stock ticker (e.g., AAPL)

Option	Required	Choices / Default	Description
`--base \<year:period>`	yes	none	Earlier filing as YEAR:PERIOD (e.g., 2023:FY) (required)
`--compare \<year:period>`	yes	none	Later filing as YEAR:PERIOD (e.g., 2024:FY) (required)
`--sections \<sections>`	no	default: risk_factors,mda,business,legal	Comma-separated section names (e.g., risk_factors,mda)
`--mode \<mode>`	no	choices: diff, raw, summary; default: diff	Output mode
`--no-qa`	no	none	Skip the QA fidelity review
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm tool insider_trades`

SEC Form 4 insider transactions with a trailing 90-day open-market summary.

Argument	Required	Description
`ticker`	yes	Stock ticker (e.g., AAPL)

Option	Required	Choices / Default	Description
`--as-of-date \<date>`	no	none	As-of filing date (YYYY-MM-DD)
`--limit \<number>`	no	none	Maximum rows to return
`--transaction-codes \<codes>`	no	none	Comma-separated Form 4 codes (P,S,A,M,F,G,C,W)
`--include-derivatives`	no	default: false	Include derivative-security rows
`--include-holdings`	no	default: false	Include ownership-statement rows
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm tool institutional_holdings`

SEC Form 13F institutional holders for a stock or the portfolio of one manager.

Argument	Required	Description
`ticker`	no	Stock ticker (e.g., AAPL); omit when using —investor-cik

Option	Required	Choices / Default	Description
`--investor-cik \<cik>`	no	none	Investor portfolio mode: SEC CIK
`--as-of-date \<date>`	no	none	As-of filing date (YYYY-MM-DD)
`--limit \<number>`	no	none	Maximum rows to return
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm tool options_overview`

A live one-call options overview: implied vs realized volatility with rank, today’s flow, the positioning book, expected moves, and probability bands.

Argument	Required	Description
`ticker`	yes	Stock ticker (e.g., TSLA)

Option	Required	Choices / Default	Description
`--as-of-date \<date>`	no	none	As-of date: ‘today’ (default) or YYYY-MM-DD (live data only)
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm tool ticker_sentiment`

A live 0-100 sentiment composite for a ticker: seven components scored vs the ticker’s own year, grouped trend / flow / positioning.

Argument	Required	Description
`ticker`	yes	Stock ticker (e.g., AAPL)

Option	Required	Choices / Default	Description
`--as-of-date \<date>`	no	none	As-of date: ‘today’ (default) or YYYY-MM-DD (live data only)
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm tool stock_prices_current`

Latest available price for one or more stock symbols, delayed by up to 15 minutes.

Argument	Required	Description
`symbols...`	yes	Stock ticker symbols (e.g., NVDA AAPL)

Option	Required	Choices / Default	Description
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm tool technical_indicators`

Standard momentum and trend indicators (RSI, MACD, SMA) for a symbol.

Argument	Required	Description
`symbols...`	yes	Stock ticker symbols (e.g., NVDA AAPL)

Option	Required	Choices / Default	Description
`--as-of-date \<date>`	no	none	As-of date, YYYY-MM-DD (default: today)
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

`finterm bundle run ticker_data`

The full ticker snapshot: earnings, guidance, the price reaction window, ratios, options sentiment, short pressure, technicals, financial statements, and pre-earnings market context, in one call.

Argument	Required	Description
`ticker`	yes	Company ticker, e.g. AAPL

Option	Required	Choices / Default	Description
`--company-name \<name>`	no	none	Company name for display and normalization
`--delivery-mode \<mode>`	no	choices: inline_result, artifact_metadata, summary_json, dataroom_sync	Requested delivery mode
`--param \<key=value...>`	no	none	Additional bundle parameter values
`--format \<format>`	no	choices: json, yaml	Render API result as json or yaml

Examples:

finterm tool financial_statements AAPL --statement-type income_statement --timeframe quarterly --as-of-date 2024-12-01
finterm tool sec_filings_search AAPL --form-type 10-K --as-of-date 2024-12-31
finterm tool sec_filing_fetch AAPL --year 2024 --period FY --sections risk_factors,mda
finterm tool sec_filing_diff AAPL --base 2023:FY --compare 2024:FY --sections risk_factors --mode summary
finterm tool options_overview AAPL
finterm tool options_sentiment AAPL --as-of-date 2024-01-15
finterm tool ticker_sentiment AAPL
finterm tool insider_trades AAPL --as-of-date 2024-03-15
finterm tool institutional_holdings AAPL --as-of-date 2024-03-15

Web Research Bundle Commands

company_deep_research is the asynchronous web-research bundle. A run executes live and requires four fiscal-period parameters: q, fy, prev_q, and prev_fy (the current and prior fiscal quarter and year). Omitting any of them fails before the API is called.

finterm bundle catalog
finterm bundle describe company_deep_research
finterm bundle run company_deep_research AAPL \
  --param q=Q1 --param fy=2025 --param prev_q=Q4 --param prev_fy=2024
finterm bundle wait <runId>
finterm bundle result <runId>
finterm bundle download <runId> --room ./datarooms/aapl
finterm runs list

Dataroom Commands

finterm dataroom exposes the read/search subset needed for local Datarooms:

finterm dataroom info <room> - Show room metadata
finterm dataroom list <room> - List room contents
finterm dataroom files <room> - List file artifacts
finterm dataroom search <room> <query> - Search file contents
finterm dataroom read <room> <ref> - Read one artifact

Examples:

finterm dataroom info ./datarooms/aapl
finterm dataroom list ./datarooms/aapl
finterm dataroom files ./datarooms/aapl
finterm dataroom search ./datarooms/aapl "revenue"
finterm dataroom read ./datarooms/aapl <ref>

Room-mutating and authoring verbs are not exposed under finterm dataroom.

Feedback and Support Commands

`finterm feedback bug|question|feature-request`

Send a bug report, question, or feature request to the Finterm team directly from the CLI (feature is an alias for feature-request). Feedback works with any authenticated key; Pro is not required. The one-line summary is a positional argument (up to 200 characters). The exact payload always prints before sending, so you (or your agent) can see every field being shared; the global --dry-run previews the payload without sending it. Agents can submit feedback on the user’s behalf after showing the payload and getting the user’s go-ahead. Options:

--body <text> - Longer Markdown detail (up to 16 KB)
--body-file <path> - Read the body from a file, or - for stdin
--command <command> - The command line that hit the issue
--tool <toolId> - The tool id involved (e.g. sec_filings_search)
--error-code <code> - The error code received (e.g. RATE_LIMITED)
--request-id <id> - A related request id (repeatable, up to 8)
--last - Attach the context of the most recent failed API call from the local request history; explicit flags take precedence

Examples:

finterm feedback bug "options_overview returned an empty positioning book" --last
finterm feedback question "does sec_filing_diff support S-1 filings?"
finterm feedback feature-request "add a CSV output mode" --body-file notes.md

To make --last accurate, the CLI keeps a local history of recent API call outcomes in ~/.finterm/recent-requests.json (capped at 20 entries, secret-shaped values redacted, file mode 0600). Feedback submissions themselves are never recorded there, and obvious credential shapes are rejected before any submission is sent.

Global Options

All commands support these global options:

Option	Description
`--dry-run`	Preview changes without executing
`--verbose`	Show detailed output
`--quiet`	Suppress non-essential output
`--json`	Output as JSON
`--color <when>`	Control colorization: auto, always, never
`--non-interactive`	Disable prompts, fail if input is required
`--debug`	Show debug information
`--experimental`	Enable preview command groups and tools

JSON Output

Add --json to any command for machine-readable output:

finterm tool ticker_sentiment AAPL --json

Exit Codes

Code	Meaning
0	Success
1	General error
2	Validation/usage error
130	Interrupted (Ctrl+C)

Environment Variables

Variable	Description
`FINTERM_API_KEY`	Account API key used for authentication (overrides the stored credentials)
`FINTERM_API_URL`	Override the Finterm API base URL (default: production)
`FINTERM_CONFIG`	Override the `~/.finterm` config directory (stored token, run ledger, recent-requests history)
`NO_COLOR`	Disable colors
`CI`	Enables non-interactive mode automatically

​Installation

​Quick Start

​Commands

​Documentation Commands

​finterm docs

​finterm prime

​finterm skill

​finterm shortcut [query]

​finterm resources [query]

​Initialization Commands

​finterm init

​Authentication Commands

​finterm auth login

​finterm auth status

​finterm auth logout

​Setup Commands

​finterm setup

​Point Tool Commands

​Tool Command Reference

finterm tool financial_statements

finterm tool options_sentiment

finterm tool sec_filings_search

finterm tool sec_filing_fetch

finterm tool sec_filing_diff

finterm tool insider_trades

finterm tool institutional_holdings

finterm tool options_overview

finterm tool ticker_sentiment

finterm tool stock_prices_current

finterm tool technical_indicators

finterm bundle run ticker_data

​Web Research Bundle Commands

​Dataroom Commands

​Feedback and Support Commands

​finterm feedback bug|question|feature-request

​Global Options

​JSON Output

​Exit Codes

​Environment Variables

​Links

Installation

Quick Start

Commands

Documentation Commands

`finterm docs`

`finterm prime`

`finterm skill`

`finterm shortcut [query]`

`finterm resources [query]`

Initialization Commands

`finterm init`

Authentication Commands

`finterm auth login`

`finterm auth status`

`finterm auth logout`

Setup Commands

`finterm setup`

Point Tool Commands

Tool Command Reference

`finterm tool financial_statements`

`finterm tool options_sentiment`

`finterm tool sec_filings_search`

`finterm tool sec_filing_fetch`

`finterm tool sec_filing_diff`

`finterm tool insider_trades`

`finterm tool institutional_holdings`

`finterm tool options_overview`

`finterm tool ticker_sentiment`

`finterm tool stock_prices_current`

`finterm tool technical_indicators`

`finterm bundle run ticker_data`

Web Research Bundle Commands

Dataroom Commands

Feedback and Support Commands

`finterm feedback bug|question|feature-request`

Global Options

JSON Output

Exit Codes

Environment Variables

Links