mozyfin-cli 0.2.9 → 0.2.10

package/README.md

@@ -1,37 +1,41 @@
 # 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.
+Mozyfin CLI brings Vietnamese market data and Mozyfin research workflows to your terminal. It is built for fast lookup, repeatable analysis, and agent-friendly command usage without exposing product internals.
 
-## Highlights
+## Why Mozyfin CLI
 
-- 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
+- **Fast market lookup** — search symbols, view profiles, read news, and inspect company data from one command line.
+- **Agent-friendly** — concise commands and predictable text output work well with Claude Code, Codex, GitHub Copilot, and other coding agents.
+- **Research-ready** — ask natural-language questions, query documents, and export larger tables to CSV when needed.
+- **Terminal-native** — use it manually, inside scripts, or as part of an agent workflow.
 
 ## Requirements
 
-- [Bun](https://bun.sh) `>= 1.1.0`
-- A Mozyfin API key — required for every command (run `mozyfin login` once before using the CLI)
+- A Mozyfin API key for authenticated features
 
-Create an API key at: https://research.mozyfin.com/settings
+Create or manage your API key at:
 
-## Install
+```text
+https://research.mozyfin.com/settings
+```
+
+## Installation
 
 ```bash
 npm install -g mozyfin-cli
+mozyfin --help
 ```
 
 Or with Bun:
 
 ```bash
 bun install -g mozyfin-cli
+mozyfin --help
 ```
 
-### Save API Key
+## Login
+
+Save your API key once:
 
 ```bash
 mozyfin login --api-key mozy_ak_xxx
@@ -55,161 +59,87 @@ mozyfin doc "định giá HPG"
 mozyfin ask "compare VNM and MSN margin trend"
 ```
 
-## Commands
+## Using With Coding Agents
 
-| 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 CLI is a good fit for agent workflows because agents can call small terminal commands instead of loading large tool schemas or internal implementation details.
 
-```bash
-mozyfin login --api-key <key>
-mozyfin logout
-mozyfin credits
+Example prompt for your agent:
+
+```text
+Use mozyfin-cli to research VNM.VN.
+Start with `mozyfin --help`, then gather profile, news, financials, and recent candles.
+Summarize the key risks and catalysts with command outputs as evidence.
 ```
 
-Auth precedence is:
+For larger tabular results, ask your agent to use CSV export:
+
+```bash
+mozyfin ohlcv VNM.VN --timeframe 1d --limit 200 --csv vnm.csv
+```
 
-1. Explicit global `--api-key <key>`
-2. `MOZYFIN_API_KEY` environment variable
-3. Saved config from `mozyfin login`
+## Commands
 
-Config is stored at:
+### Account
 
-```text
-~/.config/mozyfin-cli/config.json
+```bash
+mozyfin login --api-key <key>
+mozyfin logout
+mozyfin credits
+mozyfin doctor
+mozyfin update
 ```
 
-### Search and Profile
+### Discovery
 
 ```bash
 mozyfin search --query VNM
-mozyfin search -q "Vinamilk"
-mozyfin search -q ""              # broad search/all, depending on API behavior
 mozyfin profile VNM.VN
+mozyfin indices
 ```
 
-`search` intentionally only exposes `--query` to keep the CLI simple and aligned with the current product workflow.
-
-### News
+### News And Research
 
 ```bash
 mozyfin news --query "Vinamilk" --limit 10
 mozyfin news --entities VNM.VN,MSN.VN --topics stock,earning --limit 20
-```
-
-Allowed topics:
-
-```text
-stock, crypto, forex, tariff, economic, earning, tech, housing, mergers_and_ipo
+mozyfin doc "định giá HPG"
+mozyfin ask "summarize VNM risks and catalysts"
 ```
 
 ### Market Data
 
 ```bash
 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
+mozyfin quote VNM.VN --limit 10
 ```
 
-Allowed OHLCV timeframes:
+Supported candle timeframes:
 
 ```text
 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
+### Company Data
 
 ```bash
 mozyfin officers VNM.VN
 mozyfin subsidiary VNM.VN
-mozyfin holder VNM.VN --is-organization true --is-foreigner false
+mozyfin holder VNM.VN --is-organization true
 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
+### Financials And Analytics
 
 ```bash
 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
-
-```bash
-mozyfin ta VNM.VN --sma 20,50,200 --rsi 14 --macd
+mozyfin ta VNM.VN --sma 20,50 --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
-
-```bash
-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
-
-```bash
-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 CLI prints readable text by default, usually Markdown tables or compact key-value sections.
 
 ```bash
 mozyfin search --query VNM
@@ -221,72 +151,23 @@ mozyfin search --query VNM
 | VNM | Vietnam Dairy Products Joint Stock Company | HOSE | ... | VNM.VN |
 ```
 
-Use CSV for long datasets:
+Use CSV when you want to save or process larger datasets:
 
 ```bash
 mozyfin ohlcv VNM.VN --timeframe 1d --limit 200 --csv vnm.csv
 ```
 
-## Development
-
-```bash
-bun install
-bun run check
-bun test
-```
-
-Useful scripts:
+## Tips
 
-| 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 |
+- Use `mozyfin search --query <text>` first to find the right entity id.
+- Pass ids like `VNM.VN` into detail commands.
+- Use `doc` for document and report questions.
+- Use `ask` for open-ended research prompts.
+- Keep prompts focused; run multiple commands for multi-part research.
 
-Run from source:
+## Help
 
 ```bash
-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
-
-```text
-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
+mozyfin --help
+mozyfin <command> --help
 ```
-
-## 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.

package/package.json

@@ -1,14 +1,26 @@
 {
   "name": "mozyfin-cli",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Human- and agent-friendly CLI for Vietnamese market data via Mozyfin/Antofin APIs.",
   "type": "module",
   "bin": {
     "mozyfin": "./dist/index.js",
     "mozyfin-cli": "./dist/index.js"
   },
-  "files": ["dist", "agent-skills", "package.json", "README.md"],
-  "keywords": ["mozyfin", "antofin", "vietnam", "stocks", "market-data", "cli"],
+  "files": [
+    "dist",
+    "agent-skills",
+    "package.json",
+    "README.md"
+  ],
+  "keywords": [
+    "mozyfin",
+    "antofin",
+    "vietnam",
+    "stocks",
+    "market-data",
+    "cli"
+  ],
   "scripts": {
     "dev": "bun run src/index.ts",
     "build": "bun build ./src/index.ts --target bun --minify --outfile dist/index.js && chmod +x dist/index.js",
@@ -38,5 +50,5 @@
   "bugs": {
     "url": "https://github.com/onlyai-team/mozyfin-cli/issues"
   },
-  "homepage": "https://github.com/onlyai-team/mozyfin-cli#readme"
+  "homepage": "https://cli.mozyfin.com"
 }