feat: add tradingview-cli for composable CLI usage (#44)

* chore: add .worktrees/ to .gitignore

* feat: add tradingview-cli binary for composable CLI usage

Add a standalone CLI interface alongside the existing MCP server,
inspired by the argument that CLI tools are simpler, more composable,
and more token-efficient than MCP servers.

- New binary: `tradingview-cli` (same npm package, dual mode)
- Commands: screen stocks/forex/crypto/etf, lookup, fields, preset(s)
- Output formats: JSON (default), CSV, table
- Preset support: --preset flag with automatic symbol-based detection
- Zero new runtime dependencies (uses Node 18+ util.parseArgs)
- 47 new tests covering arg parsing, formatters, and integration
- MCP server remains 100% unchanged

* autoresearch: expand CLI tests with edge cases (+8 tests)

Add coverage for: columns override, sort-order override, malformed JSON
filters, all result shapes (pairs/crypto/etfs/symbols) in CSV/table,
preset with columns+filters merge, empty filters array.

* autoresearch: add 15 end-to-end CLI tests, gitignore .autoresearch

E2E tests verify full CLI dispatch via child process: help, version,
presets, fields, screen help, and error handling for unknown commands,
invalid asset types, missing symbols/preset names.

* docs: add CLI usage docs, update README and CLAUDE.md for dual mode

- Add CLI Usage section to README with commands, options, output formats
- Update project description to mention CLI alongside MCP
- Add CLI architecture docs to CLAUDE.md (dual entry points, cli/ helpers)
- Update package.json description and add 'cli' keyword

Author: bearmug

.gitignore

@@ -35,3 +35,9 @@ Thumbs.db
 
 # Local documentation and specs
 docs/local/
+
+# Worktrees
+.worktrees/
+
+# Autoresearch
+.autoresearch/

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-TradingView MCP Server is an unofficial Model Context Protocol server that provides access to TradingView's market screener API. It enables AI-powered stock, forex, crypto, and ETF screening through Claude Desktop or Claude Code.
+TradingView MCP Server is an unofficial Model Context Protocol server **and CLI tool** that provides access to TradingView's market screener API. It enables AI-powered stock, forex, crypto, and ETF screening through Claude Desktop, Claude Code, or the standalone `tradingview-cli` command.
 
 ## Build and Development Commands
 
@@ -13,7 +13,8 @@ npm install          # Install dependencies
 npm run build        # Compile TypeScript to dist/
 npm test             # Run all tests
 npm run test:watch   # Run tests in watch mode
-npm run dev          # Run directly with tsx (no build step)
+npm run dev          # Run MCP server directly with tsx (no build step)
+npm run dev:cli      # Run CLI directly with tsx (no build step)
 ```
 
 ### Running a single test file
@@ -28,13 +29,24 @@ For local development, use `npm run dev` which runs TypeScript directly via tsx
 
 ## Architecture
 
-### Entry Point and MCP Server Setup
-`src/index.ts` - Creates the MCP server, registers tools and resources, handles tool calls. Initializes core components:
+### Dual Entry Points
+The package has two entry points sharing all core logic:
+
+**MCP Server** — `src/index.ts`
+Creates the MCP server, registers tools and resources, handles tool calls via stdio. Initializes core components:
 - `TradingViewClient` - API client
 - `Cache` - Response caching (configurable TTL)
 - `RateLimiter` - Request throttling (configurable RPM)
 - `ScreenTool`, `FieldsTool`, `PresetsTool` - Tool implementations
 
+**CLI** — `src/cli.ts`
+Standalone CLI using Node's built-in `util.parseArgs`. Reuses the same tool classes. Output formats: JSON (default), CSV, table. No `cache.startCleanup()` (CLI is short-lived).
+
+**CLI Helpers** (`src/cli/`)
+- `parseArgs.ts` - Option configs, input builders, preset merging
+- `formatters.ts` - JSON/CSV/table output formatters
+- `help.ts` - Help text for all commands
+
 ### Core Components
 
 **API Layer** (`src/api/`)

README.md

@@ -10,10 +10,12 @@
 [![License](https://img.shields.io/github/license/fiale-plus/tradingview-mcp-server?style=flat-square)](LICENSE)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square)](https://modelcontextprotocol.io)
 
-**Unofficial** Model Context Protocol (MCP) server for TradingView's market screener API — stocks, forex, crypto & ETFs.
+**Unofficial** MCP server **and CLI** for TradingView's market screener API — stocks, forex, crypto & ETFs.
 
 ### AI-powered investment research for patient, systematic investors.
 
+**Two modes, one package:** Use as an MCP server with Claude, or as a standalone CLI tool that pipes to `jq`, `csvtool`, or any Unix workflow.
+
 </div>
 
 ---
@@ -22,6 +24,7 @@
 
 - [Features](#features)
 - [Installation](#installation)
+- [CLI Usage](#cli-usage)
 - [Configuration](#configuration)
 - [MCP Tools](#mcp-tools)
 - [Screening Fields](#screening-fields)
@@ -35,6 +38,7 @@
 
 ## Features
 
+- **Dual mode: MCP + CLI** — use as an MCP server with Claude or as a standalone `tradingview-cli` command
 - **100+ screener fields** including Piotroski F-Score, Altman Z-Score, Graham Number, analyst consensus, and dividend growth streaks
 - **18 filter operators** including `crosses_above` / `crosses_below` for golden cross detection
 - **14 pre-built strategies** covering value, growth, quality, GARP, deep value, breakouts, compounders, and macro monitoring
@@ -68,6 +72,68 @@ local-setup.bat           # Windows
 
 ---
 
+## CLI Usage
+
+After installing the package, the `tradingview-cli` command is available globally:
+
+```bash
+# List all pre-built screening strategies
+tradingview-cli presets
+
+# Screen stocks using a preset
+tradingview-cli screen stocks --preset quality_stocks --limit 10
+
+# Screen with custom filters
+tradingview-cli screen stocks --filters '[{"field":"price_earnings_ttm","operator":"less","value":15}]'
+
+# Look up specific symbols (indexes, stocks)
+tradingview-cli lookup NASDAQ:AAPL TVC:SPX NYSE:MSFT
+
+# Discover available screening fields
+tradingview-cli fields --asset-type stock --category fundamental
+```
+
+### Output Formats
+
+```bash
+# JSON (default) — pipe to jq
+tradingview-cli screen stocks --preset value_stocks | jq '.stocks[].name'
+
+# CSV — pipe to file or csvtool
+tradingview-cli screen stocks --preset value_stocks -f csv > results.csv
+
+# Table — human-readable terminal output
+tradingview-cli screen stocks --preset value_stocks -f table
+```
+
+### CLI Commands
+
+| Command | Description |
+|---|---|
+| `screen stocks [opts]` | Screen stocks by fundamental/technical criteria |
+| `screen forex [opts]` | Screen forex pairs |
+| `screen crypto [opts]` | Screen cryptocurrencies |
+| `screen etf [opts]` | Screen ETFs |
+| `lookup <symbols...>` | Look up specific symbols by ticker |
+| `fields [opts]` | List available screening fields |
+| `preset <name>` | Get a preset strategy's details |
+| `presets` | List all available presets |
+
+### Screen Options
+
+| Flag | Description |
+|---|---|
+| `--filters <json>` | Filter array as JSON string |
+| `--preset <name>` | Load a preset (merges with `--filters`) |
+| `--markets <market>` | Market to screen (repeatable, stocks/etf only) |
+| `--sort-by <field>` | Sort by field |
+| `--sort-order <asc\|desc>` | Sort direction |
+| `--limit <n>` | Max results (1-200, default 20) |
+| `--columns <col>` | Columns to include (repeatable) |
+| `-f, --format <fmt>` | Output: `json`, `csv`, or `table` |
+
+---
+
 ## Configuration
 
 ### Claude Desktop

package.json

@@ -1,11 +1,12 @@
 {
   "name": "tradingview-mcp-server",
   "version": "0.0.0-dev",
-  "description": "Unofficial MCP server for TradingView stock screener API",
+  "description": "Unofficial MCP server and CLI for TradingView stock screener API",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "tradingview-mcp-server": "dist/index.js"
+    "tradingview-mcp-server": "dist/index.js",
+    "tradingview-cli": "dist/cli.js"
   },
   "files": [
     "dist/",
@@ -15,6 +16,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",
+    "dev:cli": "tsx src/cli.ts",
     "start": "node dist/index.js",
     "test": "tsx --test src/tests/*.test.ts",
     "test:watch": "tsx --test --watch src/tests/*.test.ts",
@@ -24,6 +26,7 @@
   "keywords": [
     "mcp",
     "tradingview",
+    "cli",
     "stock-screener",
     "model-context-protocol",
     "claude",