How to Use the CLI for Single Stock Analysis with Custom Parameters in TradingAgents-CN

Run python -m cli.main analyze to launch the interactive Typer CLI, which guides you through selecting market, ticker, date, analyst team, research depth, and LLM configurations to generate a comprehensive single-stock analysis report.

The TradingAgents-CN repository provides a multi-agent financial analysis system with a command-line interface built on Typer. The CLI for single stock analysis with custom parameters enables you to configure every aspect of the analysis pipeline—from market selection and ticker validation to LLM provider choice and research depth—without writing code.

Prerequisites and API Configuration

Before running single stock analysis, you must configure API keys for your chosen LLM provider and the Finnhub data source.

Required API Keys

The CLI validates API keys in cli/main.py via the check_api_keys() function (lines 89-112). You need:

• LLM Provider Key: DashScope, OpenAI, Anthropic, or Google API key depending on your selection.
• Finnhub API Key: Required for fetching 30-day price history and ticker validation.

Configuring Environment Variables

Create a .env file in the repository root:

DASHSCOPE_API_KEY=your_dashscope_key
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key
FINNHUB_API_KEY=your_finnhub_key

Verify your configuration:

python -m cli.main config

This displays a table of available API keys as implemented in cli/main.py (lines 21-65).

Launching the Single Stock Analysis CLI

The analyze command orchestrates the full pipeline defined in cli/main.py.

Interactive Mode Walkthrough

Execute the primary command:

python -m cli.main analyze

The CLI executes get_user_selections() in cli/utils.py (lines 20-40) to prompt for:

1. Market selection: 1 for US, 2 for A-Share, 3 for Hong Kong.
2. Ticker symbol: e.g., AAPL, 600036, or 0700.HK.
3. Analysis date: Defaults to today (YYYY-MM-DD format).
4. Analyst team: Multi-select from Market, Social, News, and Fundamentals analysts (defined in cli/models.py).
5. Research depth: 1 (shallow), 3 (medium), or 5 (deep) debate rounds.
6. LLM provider: Select from available providers (DashScope, OpenAI, Anthropic, Google).
7. Quick-thinking LLM: Model for fast inference (e.g., qwen-turbo for DashScope).
8. Deep-thinking LLM: Model for complex reasoning (e.g., gpt-4o for OpenAI).

Understanding the Analysis Pipeline

After collecting inputs, run_analysis() in cli/main.py (lines 28-40) executes:

• API validation: check_api_keys() verifies provider and Finnhub keys.
• Data preparation: prepare_stock_data() in tradingagents/utils/stock_validator.py fetches 30-day history and validates ticker-market alignment.
• Graph instantiation: Creates TradingAgentsGraph from tradingagents/graph/trading_graph.py to wire selected analysts.
• Streaming execution: The graph streams reasoning chunks; cli/main.py lines 167-270 update a Rich UI layout in real-time.
• Persistence: Report sections save as Markdown files under <results_dir>/<ticker>/<date>/reports/.
• Final rendering: display_complete_report() (lines 57-92) shows consolidated analyst outputs.

Customizing Analysis Parameters

Selecting Markets and Tickers

The get_user_selections() function in cli/utils.py validates that ticker formats match selected markets:

• US: Standard symbols (e.g., AAPL, MSFT).
• A-Share: 6-digit codes (e.g., 600036, 000001).
• Hong Kong: 4-digit codes with .HK suffix (e.g., 0700.HK, 9988.HK).

Configuring the Analyst Team

Analyst selection uses the AnalystType enum defined in cli/models.py:

• Market Analyst: Technical analysis and price action.
• Social Analyst: Sentiment from social media and forums.
• News Analyst: Recent news impact assessment.
• Fundamentals Analyst: Financial statement analysis.

You can select any combination; the TradingAgentsGraph dynamically wires only the chosen agents.

Setting Research Depth and LLM Providers

Research depth controls debate rounds between agents:

• 1: Shallow (single round, faster).
• 3: Medium (balanced depth and speed).
• 5: Deep (maximum reasoning, slower).

LLM configuration happens in two tiers:

• Quick-thinking: Handles data fetching and simple transformations.
• Deep-thinking: Handles complex reasoning and final report synthesis.

Available providers and models are defined in tradingagents/default_config.py.

Non-Interactive and Programmatic Usage

While the CLI is designed for interactivity, you can script custom parameters by wrapping the internal utilities. This advanced pattern bypasses the interactive prompts:

export TRADINGAGENTS_TICKER=AAPL
export TRADINGAGENTS_DATE=2024-12-31
export TRADINGAGENTS_ANALYSTS="market,social,news,fundamentals"
export TRADINGAGENTS_DEPTH=3
export TRADINGAGENTS_PROVIDER="OpenAI"
export TRADINGAGENTS_SHALLOW="gpt-4o-mini"
export TRADINGAGENTS_DEEP="gpt-4o"

python - <<'PY'
import os
from cli.main import run_analysis
from cli import utils as u

def _env_get_ticker(_):
    return os.getenv("TRADINGAGENTS_TICKER")
def _env_get_date():
    return os.getenv("TRADINGAGENTS_DATE")
def _env_select_analysts(_):
    mapping = {
        "market":"market",
        "social":"social",
        "news":"news",
        "fundamentals":"fundamentals"
    }
    return [u.AnalystType[m] for m in os.getenv("TRADINGAGENTS_ANALYSTS").split(",")]
def _env_select_depth():
    return int(os.getenv("TRADINGAGENTS_DEPTH"))
def _env_select_provider():
    return (os.getenv("TRADINGAGENTS_PROVIDER"), "https://api.openai.com/v1")
def _env_shallow(p): return os.getenv("TRADINGAGENTS_SHALLOW")
def _env_deep(p): return os.getenv("TRADINGAGENTS_DEEP")

u.get_ticker = _env_get_ticker
u.get_analysis_date = _env_get_date
u.select_analysts = _env_select_analysts
u.select_research_depth = _env_select_depth
u.select_llm_provider = _env_select_provider
u.select_shallow_thinking_agent = _env_shallow
u.select_deep_thinking_agent = _env_deep

run_analysis()
PY

This pattern demonstrates the extensibility of the CLI architecture while maintaining the full validation and streaming capabilities defined in cli/main.py.

Output and Results

After completing the analysis pipeline, the CLI persists outputs to your configured results directory (default: results/):

results/
└── AAPL/
    └── 2024-12-31/
        └── reports/
            ├── market_report.md
            ├── social_report.md
            ├── news_report.md
            ├── fundamentals_report.md
            ├── trading_report.md
            ├── risk_report.md
            └── portfolio_report.md

The display_complete_report() function in cli/main.py renders a consolidated multi-panel view in the terminal using Rich, showing the reasoning outputs from each selected analyst alongside trading and risk management recommendations.

Summary

• The TradingAgents-CN CLI provides an interactive Typer-based interface for single stock analysis with custom parameters.
• Run python -m cli.main analyze to initiate the workflow defined in cli/main.py.
• Configure API keys in a .env file; the CLI validates these via check_api_keys() before execution.
• Customize your analysis through cli/utils.py prompts: select markets (US, A-Share, Hong Kong), ticker symbols, analyst teams (Market, Social, News, Fundamentals), research depth (1/3/5 rounds), and LLM providers with tiered thinking models.
• The pipeline instantiates TradingAgentsGraph from tradingagents/graph/trading_graph.py, pre-fetches data via prepare_stock_data(), and streams real-time results through a Rich UI.
• Results save as Markdown files under <results_dir>/<ticker>/<date>/reports/.

Frequently Asked Questions

What markets does the TradingAgents-CN CLI support?

The CLI supports three major markets as implemented in cli/utils.py: US equities (standard tickers like AAPL), A-Share (6-digit Chinese stock codes like 600036), and Hong Kong (4-digit codes with .HK suffix like 0700.HK). The prepare_stock_data() function in tradingagents/utils/stock_validator.py validates that your ticker format matches the selected market before fetching data.

How do I change the default data directory for analysis results?

Use the data-config command to modify the results path. Run python -m cli.main data-config --set /path/to/custom/data to override the default directory, or run python -m cli.main data-config --reset to restore the built-in default. This functionality is implemented in cli/main.py within the data_config() function (lines 1728-1765).

Can I run single stock analysis without interactive prompts?

While the CLI is designed for interactivity, you can script custom parameters by monkey-patching the utility functions in cli/utils.py before calling run_analysis(). Set environment variables for your desired parameters (ticker, date, analysts, depth, provider, models), then override functions like get_ticker(), select_analysts(), and select_llm_provider() to return these values instead of prompting. This advanced pattern maintains full access to the validation and streaming capabilities defined in cli/main.py.

Where are the analysis reports saved?

Final reports are persisted as Markdown files in a structured directory: <results_dir>/<ticker>/<analysis_date>/reports/. Each selected analyst generates a separate report (e.g., market_report.md, fundamentals_report.md), alongside aggregated outputs like trading_report.md and risk_report.md. The save logic is handled by the save_report_section_decorator in cli/main.py (lines 24-35), while display_complete_report() renders the final consolidated view in the terminal.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}