SAHMK CLI Quick Start

1. Installation

The SAHMK CLI is included with the Python SDK:

pip install -U sahmk

After installation, the sahmk command is available in your terminal.

2. API Key Setup

Get your free key at sahmk.sa/developers.

Option 1: Environment Variable (Recommended)

export SAHMK_API_KEY="your_api_key_here"

Add this to your ~/.bashrc or ~/.zshrc for persistence.

Option 2: Pass with Every Command

sahmk quote 2222 --api-key your_api_key_here

3. Your First Command

Fetch a stock quote for Aramco (symbol: 2222):

sahmk quote 2222

{
  "symbol": "2222",
  "name_en": "Saudi Arabian Oil Co",
  "price": 25.86,
  "change": 0.18,
  "change_percent": 0.7,
  "volume": 9803705,
  "value": 252308343.0,
  "liquidity": {
    "inflow_value": 184950463.03,
    "outflow_value": 67357881.91,
    "net_value": 117592581.12
  }
}

Use --compact for single-line output, perfect for piping:

sahmk quote 2222 --compact

4. Market Commands

Market Summary (TASI Index)

sahmk market summary

Top Gainers and Losers

sahmk market gainers --limit 5
sahmk market losers --limit 5

Volume and Value Leaders

sahmk market volume --limit 10
sahmk market value --limit 10

Sector Performance

sahmk market sectors

5. Stock Data Commands

Batch Quotes (Starter+)

sahmk quotes 2222,1120,4191

Historical OHLCV (Starter+)

sahmk historical 2222 --from 2026-01-01 --to 2026-01-31 --interval 1d

Interval options: 1d (daily), 1w (weekly), 1m (monthly).

Company Profile (Free+)

sahmk company 2222

Returns fundamentals, technicals, valuation, and analyst data (tiered by plan).

Financial Statements (Starter+)

sahmk financials 2222

Returns income statements, balance sheets, and cash flows.

Dividend History (Starter+)

sahmk dividends 2222

Returns trailing yield, upcoming distributions, and payment history.

Stock Events (Pro+)

sahmk events --symbol 2222 --limit 10

Returns AI-generated event summaries. Omit --symbol for all recent events.

6. Real-Time Streaming (Pro+)

Stream live quote updates via WebSocket:

sahmk stream 2222,1120

Quotes print as JSON lines to stdout, connection status goes to stderr. Press Ctrl+C to stop.

{"symbol":"2222","price":25.86,"change":0.18,"change_percent":0.7,"volume":9803705}
{"symbol":"1120","price":108.6,"change":0.2,"change_percent":0.18,"volume":3250100}

7. Pro Tips

• →Shell scripting: Pipe --compact output to jq for filtering:

sahmk quote 2222 --compact | jq '.price'

• →Watch mode: Monitor a stock with periodic refresh:

watch -n 30 sahmk quote 2222

• →Batch scripting: Combine with shell loops:

for sym in 2222 1120 7010; do sahmk quote $sym --compact; done

• →Error output: Errors go to stderr as JSON — your scripts won't break:

sahmk quote INVALID 2>/dev/null || echo "failed"