Mozyfin CLI

A Bun-powered command line interface for Vietnamese market data from the Mozyfin/Antofin APIs. It is designed for both humans and AI agents: short ticker-first commands, Markdown tables by default, CSV export for long datasets, and predictable plain-text errors.

Highlights

• Human-readable Markdown output by default
• CSV export with --csv <file> for spreadsheets or agent pipelines
• All commands require an API key — MOZYFIN_API_KEY, saved config, or --api-key
• Client-side 1 request/second rate limit for API friendliness
• Built-in technical indicators and risk metrics from OHLCV candles
• Automatic update check that warns when a newer CLI version is available on npm
• Mocked CLI test suite covering command wiring, auth, config, CSV, validation, and output shape

Requirements

• Bun >= 1.1.0
• A Mozyfin API key — required for every command (run mozyfin login once before using the CLI)

Create an API key at: https://research.mozyfin.com/settings

Install

npm install -g mozyfin-cli

Or with Bun:

bun install -g mozyfin-cli

Save API Key

mozyfin login --api-key mozy_ak_xxx

You can also use an environment variable:

export MOZYFIN_API_KEY=mozy_ak_xxx

Quick Start

mozyfin search --query VNM
mozyfin profile VNM.VN
mozyfin news --entities VNM.VN --topics stock,earning --limit 10
mozyfin ohlcv VNM.VN --timeframe 1d --limit 200
mozyfin financials VNM.VN --year 2024 --quarter 4
mozyfin doc "định giá HPG"
mozyfin ask "compare VNM and MSN margin trend"

Commands

| Command | Purpose | Example | | --- | --- | --- | | login | Save API key locally | mozyfin login --api-key <key> | | logout | Remove saved API key | mozyfin logout | | search | Search ticker/company/entity | mozyfin search --query VNM | | profile | Company/entity profile | mozyfin profile VNM.VN | | news | Market headlines and article search | mozyfin news --entities VNM.VN --topics stock,earning | | indices | List supported market indices | mozyfin indices | | ohlcv | Historical candles | mozyfin ohlcv VNM.VN --timeframe 1d --limit 200 | | quote | Historical quote stats | mozyfin quote VNM.VN --limit 10 | | officers | Company officers/directors | mozyfin officers VNM.VN | | subsidiary | Subsidiaries | mozyfin subsidiary VNM.VN | | holder | Major shareholders | mozyfin holder VNM.VN --is-organization true | | holder-tx | Shareholder transactions | mozyfin holder-tx VNM.VN --transaction-type buy --limit 100 | | financials | Financial statements summary | mozyfin financials VNM.VN --year 2024 --quarter 4 | | stats | Financial statistics/ratios | mozyfin stats VNM.VN --year 2024 | | ta | Technical indicators | mozyfin ta VNM.VN --sma 20,50 --rsi 14 --macd | | risk | Return, volatility, Sharpe, drawdown | mozyfin risk VNM.VN --limit 252 --risk-free 0.03 | | doc | Query analysis reports (RAG) | mozyfin doc "định giá HPG" | | ask | Ask the Mozyfin agent | mozyfin ask "analyze VNM" --timeout 300 | | credits | Check subscription usage | mozyfin credits | | doctor | Runtime/config/API health check | mozyfin doctor | | update | Upgrade CLI and refresh installed agent skills | mozyfin update | | skill | Install/remove/list agent skill packs | mozyfin skill claude |

Command Reference

Auth

mozyfin login --api-key <key>
mozyfin logout
mozyfin credits

Auth precedence is:

1. Explicit global --api-key <key>
2. MOZYFIN_API_KEY environment variable
3. Saved config from mozyfin login

Config is stored at:

~/.config/mozyfin-cli/config.json

Search and Profile

mozyfin search --query VNM
mozyfin search -q "Vinamilk"
mozyfin search -q ""              # broad search/all, depending on API behavior
mozyfin profile VNM.VN

search intentionally only exposes --query to keep the CLI simple and aligned with the current product workflow.

News

mozyfin news --query "Vinamilk" --limit 10
mozyfin news --entities VNM.VN,MSN.VN --topics stock,earning --limit 20

Allowed topics:

stock, crypto, forex, tariff, economic, earning, tech, housing, mergers_and_ipo

Market Data

mozyfin ohlcv VNM.VN --timeframe 1d --limit 200
mozyfin ohlcv VNM.VN --timeframe 1w --to 2024-12-31 --limit 52
mozyfin ohlcv VNINDEX.VN --timeframe 1d --limit 100
mozyfin quote VNM.VN --to 2024-12-31 --limit 10

Allowed OHLCV timeframes:

1h, 1d, 1w, 1mo, 1y

ohlcv works for both equities and market indices. The CLI first calls the entity endpoint, and if no candles come back it automatically falls back to the market-index endpoint (/api/v1/market/market-index/<id>/ohlcv). The id is passed through unchanged, so mozyfin ohlcv VNINDEX.VN, VN30.VN, VN100.VN, HNX30.VN, HNXIndex.VN, etc. all work without special-casing. Run mozyfin indices to list every supported index id.

Entity Details

mozyfin officers VNM.VN
mozyfin subsidiary VNM.VN
mozyfin holder VNM.VN --is-organization true --is-foreigner false
mozyfin holder-tx VNM.VN --transaction-type buy --limit 100

Note: the upstream endpoint for officers is named /office, but the returned data is officers/directors, so the CLI command uses officers for clarity.

Financials

mozyfin financials VNM.VN --year 2024 --quarter 4
mozyfin financials VNM.VN --year 2024 --quarter 4 --statement-type BALANCE_SHEET
mozyfin stats VNM.VN --year 2024

financials summarizes nested statement values into common readable columns such as net_sales, gross_profit, profit_after_tax, total_assets, owner_equity, and net_operating_cash_flow.

Analytics

mozyfin ta VNM.VN --sma 20,50,200 --rsi 14 --macd
mozyfin risk VNM.VN --limit 252 --risk-free 0.03

ta and risk compute over chronological candles even when the API returns latest-first data.

Document Query

mozyfin doc "định giá HPG"
mozyfin doc "VNM Q4 2024 earnings analysis"
mozyfin doc "so sánh biên lợi nhuận VNM và MSN"

Queries analysis reports using natural language via RAG. Returns structured Markdown with sections:

• Entities — knowledge graph entities extracted from reports
• Relationships — connections between entities
• Document Chunks — retrieved report passages relevant to the query
• References — source documents mapped to chunks
• Context — grounding instructions from the RAG system

Requires an API key.

Agent

mozyfin ask "summarize VNM risks and catalysts"
mozyfin ask "what is FPT's revenue growth outlook?" --timeout 600

The command creates an auto-mode chat, sends the prompt, polls until the message finishes, and prints the final text response.

Guidance:

• Ask one focused question per call. Don't stuff multiple questions into a single prompt — the agent answers better and faster with a clear, narrow ask. Run mozyfin ask again for the next question.
• --timeout <seconds> defaults to 300 (5 minutes). Raise it for deeper research prompts.

Output

Default output is Markdown table or key-value text:

mozyfin search --query VNM

| symbol | name | exchange | market_cap | id |
| --- | --- | --- | --- | --- |
| VNM | Vietnam Dairy Products Joint Stock Company | HOSE | ... | VNM.VN |

Use CSV for long datasets:

mozyfin ohlcv VNM.VN --timeframe 1d --limit 200 --csv vnm.csv

Development

bun install
bun run check
bun test

Useful scripts:

| Script | Description | | --- | --- | | bun run dev -- <args> | Run CLI from source | | bun test | Run unit/CLI tests | | bun run lint | Check formatting/linting | | bun run format | Format files | | bun run check | Format/lint with write fixes |

Run from source:

bun run src/index.ts search --query VNM

Test Coverage

The test suite uses Bun's test runner plus a mocked local HTTP server. It covers:

• API URL construction and endpoint mapping
• HTTP response and error parsing
• CLI command output shape
• Query parameter mapping for command options
• Auth precedence and config persistence
• CSV file output
• Empty data rendering
• Validation errors and missing API key errors
• ask polling and malformed response handling
• Technical indicator and risk helper behavior

Project Structure

src/index.ts          CLI command definitions
src/lib/api.ts        API client, auth, rate limit, URL construction
src/lib/config.ts     Local config load/save/clear
src/lib/format.ts     Markdown, key-value, CSV formatting
src/lib/analytics.ts  SMA, EMA, RSI, MACD, risk metrics
test/*.test.ts        Unit and mocked CLI tests

Notes for AI Agents

• Prefer Markdown output for short responses and --csv <file> for large tables.
• Use search --query <text> to discover entity ids, then pass ids such as VNM.VN into detail commands.
• Do not use removed commands/options such as markets, exchanges, events, or ask --no-wait.
• officers returns people and roles, not physical office addresses.
• Every command requires an API key — call mozyfin login --api-key <key> (or set MOZYFIN_API_KEY) before any other command.
• Use doc for natural language queries against analysis reports (RAG); use ask for open-ended AI research that may call multiple data sources.
• If your CLI version is outdated the CLI prints an ⚠️ warning to stderr at the end of each run; pipe stderr separately if you parse output.

License

Private/internal unless a license is added.