CLI commands

The complete reference for the teemtape CLI. For a guided introduction see using the CLI (end users) or driving the CLI (agents).

Global flags

These apply to every command:

--api-url <url>    Worker API base URL (env: TEEMTAPE_API_URL)
--token <token>    Watchlist token (env: TEEMTAPE_TOKEN)
--handle <name>    Anonymous handle for posted notes (env: TEEMTAPE_HANDLE)
--web-url <url>    Web app URL for share links (env: TEEMTAPE_WEB_URL)
--access-token <pat>  teemtape Pro access token (env: TEEMTAPE_ACCESS_TOKEN)
--dashboard-url <url> teemtape Pro app URL (env: TEEMTAPE_DASHBOARD_URL)
--json             Machine-readable JSON output (use this for agent workflows)

See the configuration reference for how settings are resolved.

init

Create a new anonymous watchlist and persist the token locally.

teemtape init [--json]

{
  "token": "6f1ed002ab5595859014ebf0951522d9",
  "url": "https://www.teemtape.com/w/6f1ed002ab5595859014ebf0951522d9",
  "configPath": "/home/user/.config/teemtape/config.json"
}

search

Search the symbols catalog (US, NZX, ASX, NSE, …). Does not require a watchlist token. Every row includes exchange and currency; a bare query like amp returns both AMP (NYSE) and AMP.AX (ASX).

teemtape search [QUERY] [options] [--json]

Options:
  --symbol <text>   Filter by ticker substring only
  --name <text>     Filter by company name substring only
  --limit <n>       Max results (default 20, max 100)
  --offset <n>      Skip first n matches (pagination)
  --sort <field>    ticker | title (default: ticker)
  --exchange <code> Only one market: US, NZX, ASX, NSE, … (aliases such as NASDAQ work)

Combine --symbol and --name with AND logic. A positional QUERY matches either field.

list

Show delayed quotes.

teemtape list [--symbols A,B] [--json]

Without --symbols, it fetches the current watchlist symbols first. With --symbols, it quotes those tickers directly (comma-separated, case-insensitive).

add

Add a ticker to the watchlist. The symbol is normalized to its canonical form: upper-case, and EXCHANGE:TICKER aliases (asx:bhp) become the suffixed symbol (BHP.AX). Non-US listings must carry their suffix — see symbols.

teemtape add <SYMBOL> [--json]

notes

Read the anonymous note thread for a symbol (newest first).

teemtape notes <SYMBOL> [--json]

note

Post an anonymous note. CLI notes are tagged source: "cli" and attributed to your handle (or agent-cli if none is set).

teemtape note <SYMBOL> --message "<text>" [--json]
# shorthand:
teemtape note <SYMBOL> -m "<text>" [--json]

handle

Show, set, or generate your anonymous handle.

teemtape handle                # show current handle
teemtape handle <name>         # claim a specific handle (must be available)
teemtape handle --generate     # get a fresh, unique handle

Print the shareable watchlist link.

teemtape share [--json]

config

Show the resolved configuration. The token is masked.

teemtape config [--json]

Output and exit codes

--json writes pretty-printed JSON to stdout; see JSON output shapes.
Errors are written to stderr as error: … with a non-zero exit code.

Save a teemtape Pro personal access token so the CLI (and any agent driving it) can open private watchlists and act with the role the owner granted.

teemtape login [ACCESS_TOKEN] [--json]

Create the token in the teemtape Pro app first. If you omit the argument the CLI prompts for it. The token is verified against GET /api/whoami before it is saved to the config file (0600); teemtape config shows it masked.

{ "handle": "trader_jane", "accessToken": "****", "configPath": "/home/user/.config/teemtape/config.json" }

Without a valid token, private watchlists answer:

error: this watchlist is private — sign in to continue (HTTP 401)
  This watchlist is private. Run `teemtape login` (sign in at https://app.teemtape.com).

logout

Forget the saved access token.

teemtape logout [--json]