> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finterm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# finterm CLI

> Public authenticated CLI for Finterm account, data, bundle, Dataroom, and feedback workflows

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:

```bash theme={"system"}
npx @finterm-ai/cli@latest --help
```

Or install globally so the `finterm` command is always available:

```bash theme={"system"}
npm install -g @finterm-ai/cli
```

Finterm requires Node.js 22.12 or newer.

## Quick Start

```bash theme={"system"}
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

#### `finterm auth login`

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:

```bash theme={"system"}
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.

```bash theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
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                                                     |

## Links

* npm package: [https://www.npmjs.com/package/@finterm-ai/cli](https://www.npmjs.com/package/@finterm-ai/cli)