@finok/cli

Command-line interface for the Finok financial data API. Query stock quotes, financial statements, market activity, and more from your terminal.

Install

# From the monorepo root
pnpm install
pnpm --filter @finok/cli build

# Link globally (optional)
pnpm --filter @finok/cli link --global

Authentication

# Log in with your API key
finok auth login <your-api-key>

# Check authentication status
finok auth status

# Log out
finok auth logout

Environment variables take precedence over saved config:

export FINOK_API_KEY=your-api-key
export FINOK_BASE_URL=https://finok-web.vercel.app/api/v1  # optional, default

When FINOK_API_KEY is set, finok auth status will indicate (from env).

Global Options

All data commands support --format json|table|csv (default: json).

finok quote AAPL --format table
finok history AAPL --format csv > prices.csv

Other global options:

-V, --version   Print version number
-h, --help      Show help

Commands

search -- Search for Companies

finok search Apple                       # search by company name (default)
finok search AAPL --by symbol            # search by ticker symbol
finok search 0000320193 --by cik         # search by CIK number
finok search US0378331005 --by isin      # search by ISIN
finok search 037833100 --by cusip        # search by CUSIP
finok search tech --limit 5              # limit number of results

| Option | Description | Default | |---|---|---| | --by <type> | Search type: name, symbol, cik, cusip, isin | name | | --limit <n> | Maximum number of results | (all) |

quote -- Get a Stock Quote

finok quote AAPL
finok quote MSFT --format table

profile -- Get Company Profile

finok profile AAPL
finok profile TSLA --format table

Financial Statements

Three commands share the same options: income, balance, and cashflow.

finok income AAPL                        # annual income statement
finok income AAPL --period quarter       # quarterly
finok income AAPL --limit 4              # last 4 periods
finok income AAPL --growth               # year-over-year growth rates

finok balance AAPL                       # balance sheet
finok balance AAPL --period quarter --limit 2

finok cashflow AAPL                      # cash flow statement
finok cashflow AAPL --growth

| Option | Description | Default | |---|---|---| | --period <type> | annual or quarter | annual | | --limit <n> | Number of periods to return | (all) | | --growth | Show growth rates instead of raw values | off |

Valuation and Metrics

finok metrics AAPL                       # key metrics (P/E, EV/EBITDA, ROE, etc.)
finok metrics AAPL --period quarter --limit 4

finok ratios AAPL                        # financial ratios
finok ratios AAPL --period quarter --limit 4

finok dcf AAPL                           # discounted cash flow valuation

metrics and ratios support --period and --limit. dcf takes only a symbol.

| Option | Description | Default | |---|---|---| | --period <type> | annual or quarter | annual | | --limit <n> | Number of periods to return | (all) |

history -- Historical Prices

finok history AAPL                               # full OHLCV history
finok history AAPL --from 2025-01-01 --to 2025-12-31
finok history AAPL --format csv > aapl.csv       # export to CSV

| Option | Description | |---|---| | --from <date> | Start date (YYYY-MM-DD) | | --to <date> | End date (YYYY-MM-DD) |

Market Activity

finok insider AAPL                       # insider trading (SEC Form 4)
finok ratings AAPL                       # analyst upgrades and downgrades
finok congress AAPL                      # U.S. House member trades (default)
finok congress AAPL --chamber senate     # U.S. Senate member trades

| Option | Description | Default | |---|---|---| | --chamber <chamber> | house or senate (congress only) | house |

list -- List Financial Instruments

finok list stocks                        # all stocks
finok list etfs                          # all ETFs
finok list indexes                       # market indexes
finok list exchanges                     # supported exchanges
finok list sectors                       # available sectors
finok list industries                    # available industries
finok list commodities                   # commodities

Valid types: stocks, etfs, indexes, exchanges, sectors, industries, commodities.

screener -- Stock Screener

finok screener --sector Technology --limit 10
finok screener --exchange NASDAQ --market-cap-gt 1000000000
finok screener --industry "Software" --market-cap-lt 500000000

| Option | Description | |---|---| | --sector <sector> | Filter by sector | | --industry <industry> | Filter by industry | | --exchange <exchange> | Filter by exchange | | --market-cap-gt <n> | Minimum market cap | | --market-cap-lt <n> | Maximum market cap | | --limit <n> | Maximum number of results |

treasury -- U.S. Treasury Rates

finok treasury
finok treasury --from 2025-01-01 --to 2025-06-30
finok treasury --format table

| Option | Description | |---|---| | --from <date> | Start date (YYYY-MM-DD) | | --to <date> | End date (YYYY-MM-DD) |

Output Formats

| Flag | Description | |---|---| | --format json | Pretty-printed JSON (default) | | --format table | Column-aligned plain text table | | --format csv | CSV, suitable for piping to files or other tools |

# Pipe JSON to jq
finok quote AAPL | jq '.[] | {symbol, price}'

# Export to CSV
finok history AAPL --from 2025-01-01 --format csv > prices.csv

# Pipe to other tools
finok list stocks --format csv | head -20

Configuration

Config is stored at ~/.config/finok/config.json. Valid keys: api_key, base_url.

finok config set base_url https://your-custom-endpoint.com/api/v1
finok config get base_url
finok config list

finok config list prints all values with the API key masked for safety.

Environment variables (FINOK_API_KEY, FINOK_BASE_URL) always take precedence over saved config values.