tw-stock

A command-line tool for quickly searching Taiwan stock market information, including real-time prices, market indices, and historical trading data.

The 3.0.0-rc.1 release candidate removes the crawler command and the TDCC/local-directory runtime dependency. Read the v3 migration notes before upgrading an existing installation.

Installation

npm install -g tw-stock

Commands

stock — Search stock information

tw-stock stock [stock_code]

| Option | Description | | ----------------------- | -------------------------------------------------- | | -l, --listed <listed> | Market type: tse (default) or otc | | -m, --multiple | Search multiple stock codes (hyphen-separated) | | -f, --favorite | Search stocks from favorite list | | -o, --oddLot | Search odd-lot trading data | | -d, --date <date> | Search historical data (YYYY-MM or YYYY-MM-DD) | | --details | Show detailed stock data (default: true) |

Examples:

# Search a single TSE stock
tw-stock stock 2330

# Search an OTC stock
tw-stock stock 6488 -l otc

# Search multiple stocks
tw-stock stock 2330-2317-2454 -m

# Search historical monthly data
tw-stock stock 2330 -d 2025-01

# Search historical daily data
tw-stock stock 2330 -d 2025-01-15

Stock quote tables show the exchange trade date/time in Taipei time and a status: 今日成交 (trade dated today), 前期成交 (earlier session), or 無成交價 (price unavailable). Missing or invalid dates are marked explicitly. Today's date alone does not guarantee the quote is current; check its timestamp. When a quote table exceeds the terminal width, it switches to code, company, price, and status columns, with Taipei timestamps below. Terminals narrower than 60 columns use stacked quote cards. Long names wrap instead of being truncated. Output without a reported terminal width keeps the requested table layout.

Favorite lists, rankings, and institutional summary/stock tables also adapt to terminal width: names wrap first, then rows become stacked cards if the other columns cannot fit. Every field is retained, including ranking metrics and institutional totals. Daily reports do not imply live quote freshness. See representative terminal output for 40-column examples, unavailable names, and previous-session/missing-date quotes.

index — Search market indices

tw-stock index [code]

Supported indices: TAIEX, TWO, FRMSA

| Option | Description | | ---------------------- | --------------------------------------------- | | -m, --multiple | Search multiple indices | | -t, --time <time...> | Specify time range (HHMM format, 0900–1330) | | -c, --chart | Display ASCII chart |

Examples:

# Search TAIEX (default)
tw-stock index

# Search with ASCII chart
tw-stock index TAIEX -c

# Search multiple indices
tw-stock index TAIEX-TWO -m

# Search within a specific time range
tw-stock index TAIEX -t 0900 1100

institutional — Institutional investors buy/sell data

tw-stock institutional [stock_code]

View daily buy/sell data from the three major institutional investors (三大法人買賣超). Without a stock code, displays the summary table.

| Option | Description | | ----------------------- | ------------------------------------- | | -l, --listed <listed> | Market type: tse (default) or otc | | -d, --date <date> | Search specific date (YYYY-MM-DD) | | -n, --number <number> | Number of results to show |

Examples:

# Show institutional summary for today
tw-stock institutional

# Show institutional data for a specific stock
tw-stock institutional 2330

# Show OTC institutional data for a specific date
tw-stock institutional 6488 -l otc -d 2025-01-15

rank — Daily stock ranking

tw-stock rank

Show daily stock ranking by price change or volume (當日漲跌幅排行).

| Option | Description | | ----------------------- | ----------------------------------------- | | -l, --listed <listed> | Market type: tse (default) or otc | | -d, --date <date> | Search specific date (YYYY-MM-DD) | | -n, --number <number> | Number of results to show (default: 10) | | --losers | Show top losers instead of gainers | | --volume | Sort by volume |

Examples:

# Show top 10 gainers (default)
tw-stock rank

# Show top 20 losers
tw-stock rank --losers -n 20

# Show top 10 by volume for OTC
tw-stock rank --volume -l otc

# Show ranking for a specific date
tw-stock rank -d 2025-01-15

favorite — Manage favorite stocks

tw-stock favorite              # List all favorite stocks (default)
tw-stock favorite list         # List all favorite stocks
tw-stock favorite create       # Create favorite file
tw-stock favorite add <code>   # Add a stock code
tw-stock favorite delete <code> # Remove a stock code

completion — Shell tab-completion

tw-stock completion           # Setup shell tab-completion
tw-stock completion --cleanup # Remove completion from shell profile

Development and verification

See Project Improvement TODO for prioritized work and completion criteria.

Price lookups do not download the TDCC directory or require stock.json. Multiple-stock and favorite price queries resolve both markets through MIS. Multiple-stock requests deduplicate candidates and use MIS batches of up to 100 candidates (each requested code contributes TSE and OTC candidates). Favorite name lookups use batches of up to 50 requested codes. Empty lists and duplicate additions need no request. If names cannot be fetched, listing still shows saved codes; failed additions leave favorites unchanged. An unresolved MIS symbol cannot be added, even if it exists in another directory.

Quote results retain successful rows when a batch fails and warn about partial failures; a request with no usable result is fatal. Fatal failures exit with status 1, while partial results with warnings exit with status 0. Favorites are stored as ./favorite.json in the current working directory, using { "stockCodes": ["2330"] }. Writes are schema-validated and atomic. The old stock.json is ignored and may be manually deleted after checking whether another tool uses it. MIS coverage is limited to symbols it resolves for the requested market.

Quote timestamps use Taipei time. Odd-lot output prefers MIS tt and falls back to t; either field can be absent or reflect a previous session. A numeric quote does not guarantee freshness. Output adapts to terminal width without dropping fields.

See migration notes, future feature evaluations, and the draft PR description for release context.

Use Node from .nvmrc and the Yarn version declared in package.json. Install dependencies with yarn install --immutable.

• yarn test runs unit tests.
• yarn lint checks source formatting and imports.
• yarn test:e2e builds the CLI and runs fixture-backed command workflows in temporary directories. It does not require exchange connectivity.
• yarn test:live builds the CLI and checks external market-data services. Run it explicitly with network access; upstream errors fail the checks.

PR checks include deterministic E2E tests. The Live market data smoke tests workflow can be started manually in GitHub Actions. External snapshots may represent the last trading session; an unavailable price is not a live quote.

Screenshots

Search TSE Stock

Search OTC Stock

Search Multiple Stocks