Agent-First Stock Alerts CLI for AI Agents

Why a CLI for agents?

AI agents that trade or monitor markets face a fundamental tension: they need fresh market data every turn, but polling APIs burns tokens and context window on repetitive HTTP calls and HTML parsing. Web forms don't fit agent workflows, and most stock alert platforms are designed for humans clicking buttons, not for machines piping JSON.

The StockTalker AI CLI solves this with a single Rust binary that returns structured JSON on stdout. Agents — whether Claude Code, Codex, Cursor, Hermes, or any harness that can run shell commands — can install it, pipe the output, and create alerts that the backend monitors deterministically. No polling, no HTML scraping, no extra token burn.

One alert create command registers a condition; the backend checks it every cycle and sends email when triggered. For agents, this means up to ~80% fewer tokens spent on market observation compared to polling every turn.

What you get

• A compiled Rust CLI — single binary, no runtime dependencies.
• Deterministic monitoring engine: once an alert is structured, threshold checks and notifications are code, not AI.
• A web dashboard to inspect, edit, and organize alerts created by your agent.
• Email notifications when conditions are met. Webhooks on the roadmap.

How it works

Public routes — no auth needed

Check the API health:

$ stocktalkerai status -o json
{"data":{"status":"ok","version":"1.0","service":"stocktalkerai-api"}}

Fetch a stock price with market snapshot (real data, live API):

$ stocktalkerai price AAPL -o json
{"data":{"price":332.96,"change":11.3,"changePercent":3.51,"marketcap":4893531165426,"sma20":319.94,"rsi14":57.3,"low52":201.5,"high52":334.98,"volume":35592826,"pe":40.3,"changePercentYTD":22.47}}

Authenticated routes — manage alerts

Export your API key and create an alert from natural language:

$ export STOCKTALKERAI_API_KEY="sk_..."

$ stocktalkerai alert create \
    "Email me when AAPL drops below $300" \
    --note "buy-the-dip watch" \
    --pin \
    --color blue \
    -o json

The response contains the created alert with a Firestore-style document ID:

{
  "data": {
    "success": true,
    "message": "Alert created successfully. You will be notified at the email address on file.",
    "createdAlert": {
      "id": "abc123def456",
      "ticker": "AAPL",
      "status": "active",
      "description": "Email me when AAPL drops below $300"
    }
  }
}

List all your active alerts:

$ stocktalkerai alert ls -o json
{
  "data": [
    {
      "id": "abc123def456",
      "ticker": "AAPL",
      "description": "Email me when AAPL drops below $300",
      "status": "active",
      "note": "buy-the-dip watch",
      "pinned": true,
      "color": "blue"
    }
  ]
}

Other authenticated commands:

• stocktalkerai account -o json — your tier and active alert count
• stocktalkerai alert get <id> -o json — full alert details with calculated fields
• stocktalkerai alert edit <id> --note "updated note" -o json — update metadata
• stocktalkerai alert archive <id> -o json — soft-delete an alert
• stocktalkerai list ls -o json — retrieve all alert-list groups

Customize how alerts are organized

The CLI lets you attach metadata at creation or edit time. You can organize alerts into lists (e.g. "tech stocks", "earnings watch"), add notes for agent-to-human context, pin important alerts to the top, and assign colors (blue, green, yellow, red, purple). These are the same primitives available in the dashboard — agents and humans share the same data model.

$ stocktalkerai alert create "NVDA above $900" \
    --list "my-tech-watch" \
    --note "Nvidia breakout target" \
    --pin \
    --color green \
    -o json

Get started

1. Install the CLI

Tell your agent to clone the repo and build from source:

git clone https://github.com/StockTalker-AI/stocktalkerai-cli
cd stocktalkerai-cli
cargo build --release
# Binary: ./target/release/stocktalkerai

On Linux you may need pkg-config and libssl-dev. See AGENTS.md for the full setup guide. Agents that can read the repo can install themselves by following that file.

2. Get an API key

Create an account at app.stocktalkerai.com. In the dashboard, scroll to the AI & Agents section (footer area) to generate an API key. Export it in your agent's environment:

export STOCKTALKERAI_API_KEY="sk_..."

Alternatively, pass it per command: stocktalkerai alert ls --api-key "sk_..." -o json.

3. First commands

Try these with your agent (no key needed for the first two):

# Public — no auth
stocktalkerai status -o json
stocktalkerai price AAPL -o json
stocktalkerai price BTC-USD --history -o json

# Authenticated — requires STOCKTALKERAI_API_KEY
stocktalkerai account -o json
stocktalkerai alert create "Notify me when NVDA crosses $1000" --pin -o json
stocktalkerai alert ls -o json

The tool-catalog.json in the repo provides schemas for agent harnesses that support function calling.

The human loop: dashboard as control center

Alerts created by your agent appear in the StockTalker AI dashboard alongside any you create manually. You can edit the description, change the list, add a note for your agent to read later, or archive it. Notes are bidirectional: your agent writes context, you read it; you write instructions, your agent reads them.

The dashboard is also where you manage your API keys (AI & Agents section) and see account-wide usage. No feature is locked behind the CLI — it's the same data, two interfaces.

Frequently asked questions