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 by identifier (symbol shown here): 2222):

sahmk quote 2222

sahmk quote "أرامكو السعودية"

{
  "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

Quote commands accept symbol, Arabic name, English name, or alias. If input is ambiguous, rerun with the exact symbol.

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,الراجحي,stc

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 "Saudi Aramco" --compact | jq '.price'

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

watch -n 30 sahmk quote 2222

• →Batch scripting: Combine with shell loops:

for id in 2222 "الراجحي" "stc"; do sahmk quote "$id" --compact; done

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

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