CLI Reference

Complete guide to the Copinance OS CLI (copinance_os.interfaces.cli). The console entry main parses argv: known subcommands go to a lazy Typer app (analyze, cache, market, profile, version); anything else (after optional --json, --stream, or --include-prompt) is treated as a natural-language research question and runs question-driven market analysis with the full tool suite (same underlying path as analyze macro --question, default macro context). Otherwise, commands resolve services from the DI container and run jobs through the same DefaultJobRunner / ResearchOrchestrator stack as library integrations.

Command Overview

Running Commands

After installation:

# Invoke any CLI subcommand (analyze, market, profile, cache, version)
copinance <command>

Without installation:

# Run CLI as a module from repo root (no pip install required)
python -m copinance_os.interfaces.cli <command>

Performance: copinance --help, copinance help, and copinance version load quickly because heavy subcommands (analyze, cache, market, profile) are loaded only when you run them. See Architecture — Container and performance for the design.

Natural language at the root

When the first token is not analyze, cache, market, profile, or version, the CLI treats the line as a single question (tools + LLM), with optional flags before the question:

# Question-driven market analysis (default macro-style context: SPY, broad indicator set)
copinance "How is Tesla doing financially?"
copinance --stream "What is the VIX?"
copinance --json "What is the VIX?"
copinance --include-prompt "Compare credit spreads to last year"
copinance --json --include-prompt "Summarize labor and inflation"

• --json: print RunJobResult JSON to stdout (same shape as copinance analyze --json macro --question "…"). Disables --stream.
• --stream: print LLM tokens to stdout during the run (question-driven only). Ignored with --json.
• --include-prompt: include rendered prompts in saved results (when not using --json, behavior matches analyze question-driven runs).

Like analyze, root copinance "…" is single-turn: one natural-language question per invocation. Multi-turn conversation (prior Q&A in the same thread) is library-only—use AnalyzeMarketRequest with conversation_history in Python (same underlying path as this CLI entry); see Library — Multi-turn question-driven analysis.

For symbol-scoped or instrument flows, use copinance analyze equity|options|macro instead.

Machine-readable output (--json)

Use --json on the command group (before the subcommand) to print JSON to stdout instead of Rich tables—suitable for scripts, CI, and piping.

Placement: for analyze and market, put --json on the group before the subcommand. For the root question form, put --json (and optionally --include-prompt) before the question string.

copinance analyze --json equity AAPL --timeframe mid_term
copinance analyze --json macro --question "Risk-on or risk-off?"
copinance --json "Summarize labor and inflation"
copinance market --json quote AAPL
copinance market --json search "Apple" --limit 5
copinance market --json history AAPL --start 2026-01-01 --end 2026-03-14 --interval 1d
copinance market --json options SPY
copinance market --json fundamentals AAPL --periods 5

Rich human output and saving results under .copinance/results/v2/ still apply to analyze when --json is not used.

Streaming question-driven output (--stream)

Use --stream on the analyze group (before equity, options, or macro) or at the root before a natural-language question to print LLM tokens to stdout as they are generated during question-driven tool loops. --json turns streaming off. After the run, Rich still prints the same Analysis panel (markdown) so you always have a readable block for copy-paste, plus run metadata and the saved file path. Library-oriented streaming options (LLMConfig, providers) are described in Using as a Library — LLM text streaming.

copinance analyze --stream equity AAPL --question "What is the beta?"
copinance analyze --stream macro --question "Risk-on or risk-off?"
copinance --stream "Summarize credit conditions"

Version

# Print Copinance OS version (e.g. "Copinance OS v0.1.0")
copinance version

Market Commands

The market group accepts --json (see Machine-readable output).

Search Instruments

Search market instruments by symbol or display name.

# Search by display name; returns up to 10 matches (default)
copinance market search "Apple"
 
# Search by symbol with at most 5 results and symbol-only matching
copinance market search "AAPL" --limit 5 --mode symbol

Options:

• --limit <number>: Maximum results (default: 10)
• --mode <mode>: Search mode - auto, symbol, or general

Current Quote

Fetch the latest market quote for an instrument. Uses the same cache as in question-driven analysis.

# Get current price, volume, and other quote data for AAPL (uses cache)
copinance market quote AAPL
 
# Get quote for SPY and bypass cache to fetch fresh data
copinance market quote SPY --no-cache

Options:

• --no-cache: Bypass cache and fetch fresh data

Historical Data

Fetch historical OHLCV data for an instrument and date range. Uses the same cache as in question-driven analysis.

# Daily OHLCV for AAPL between two dates (default interval 1d)
copinance market history AAPL --start 2026-01-01 --end 2026-03-14
 
# Hourly data for SPY over a range; limit 0 shows all rows
copinance market history SPY --start 2026-03-01 --end 2026-03-14 --interval 1h --limit 0

Options:

• --start <date>: Start date in YYYY-MM-DD
• --end <date>: End date in YYYY-MM-DD
• --interval <interval>: One of 1d, 1wk, 1mo, 1h, 5m, 15m, 30m, 60m
• --limit <number>: Maximum rows to display (default: 0 = show all)
• --no-cache: Bypass cache and fetch fresh data

Options Chain Snapshot

Fetch an options chain for an underlying symbol. The table includes Delta, Gamma, Theta, Vega, and Rho by default when Greek columns are enabled: values are filled using analytic European BSM via QuantLib when the snapshot has an underlying price, each row has implied volatility, and the chain expiry is not before today (default expiry is the earliest listed date on or after today so you do not get a rolled-off front month). Otherwise those cells show -. Uses the same cache as in question-driven analysis; with --side all, calls and puts are interleaved so a small limit shows both.

# List options for AAPL (default expiration; all sides; Greek columns on; uses cache)
copinance market options AAPL
 
# List only call options expiring on 2026-06-19 for AAPL
copinance market options AAPL -e 2026-06-19 -s call
 
# Refresh from provider (e.g. after upgrade or if cache has no Greeks)
copinance market options SPY --no-cache
 
# Narrow terminal: hide Greek columns
copinance market options MSTR --side all --limit 20 --no-greeks
 
# Two expiries: one table each (JSON: multi_expiration + expirations array)
copinance market options AAPL -e 2026-06-19 -e 2026-09-18

Options:

• -e / --expiration <date>: Expiration in YYYY-MM-DD (default when omitted: earliest listed on or after today). Repeat for multiple expiries.
• -s / --side <side>: call, put, or all
• --limit / -n <number>: Maximum contracts to show (default: 0 = show all)
• --no-cache: Bypass cache and fetch fresh data
• --no-greeks: Hide Delta/Gamma/Theta/Vega/Rho columns

Tuning BSM inputs: set COPINANCEOS_OPTION_GREEKS_RISK_FREE_RATE and optional COPINANCEOS_OPTION_GREEKS_DIVIDEND_YIELD_DEFAULT (see Configuration). Metadata keys are documented in Options & Greeks.

Reading the Greek columns

Greeks come from European Black–Scholes–Merton via QuantLib (AnalyticEuropeanEngine), using the chain’s underlying price and each row’s implied volatility (after normalization for Yahoo-style data).

Moneyness (typical patterns):

• Deep in-the-money calls (strike well below spot): delta ≈ 1, gamma ≈ 0, vega ≈ 0—delta is near its upper bound, so curvature and volatility sensitivity are small.
• Deep out-of-the-money puts (strike well below spot, tiny premium): delta ≈ 0, and gamma, vega, and theta are often tiny; the table shows 0 or scientific notation when values are negligible, and rounds floating-point dust to zero so harmless noise does not look like a large negative delta.
• Near the money (strikes around spot): gamma and vega are usually largest; call delta moves from roughly 0 toward 1 as strike falls; put delta moves from roughly 0 toward −1 as strike rises through the money.

Rho: For this setup, call rho is typically positive; European put rho is often negative. Signs align with “sensitivity of option value to the risk-free rate” under the same model inputs.

Theta (important): QuantLib’s theta() is not the same as a casual “dollars decay per calendar day” figure you might see on a retail chain. It follows QuantLib’s definition for the analytic engine (time decay in the library’s units). Near expiry and at the money, magnitude can look very large next to the option last price—that usually reflects how theta is scaled in the engine, not that the option literally loses that many dollars per day. For publication-grade “daily theta” you would convert from QuantLib’s convention (see QuantLib Greeks and library docs) or bump the price with a small time step.

Implied volatility in the table: After normalization, a printed IV of 0.94 means about 94% annualized σ (fractional form). Values above 1 from Yahoo were converted from percent points (see Options & Greeks).

Fundamentals

Fetch fundamental data for an equity (financial statements, ratios, and key metrics). Uses the same cache as in question-driven analysis.

# Fetch fundamentals for AAPL (default: 5 annual periods, cached)
copinance market fundamentals AAPL
 
# Five years of annual financials for MSFT
copinance market fundamentals MSFT --periods 5 --period-type annual
 
# Eight quarters of AAPL data, bypass cache for latest figures
copinance market fundamentals AAPL --period-type quarterly --periods 8 --no-cache

Options:

• --periods <number> / -n: Number of periods (e.g. 5 years or 5 quarters) (default: 5)
• --period-type <type>: annual or quarterly (default: annual)
• --no-cache: Bypass cache and fetch fresh data

Profile Commands

Profiles customize analysis output based on your financial literacy level.

Note: When you run analyze without a profile, the system will prompt you to set your financial literacy level for more personalized results.

Create Profile

# Create a profile with intermediate literacy and an optional display name
copinance profile create --literacy intermediate --name "My Profile"

Literacy levels: beginner, intermediate, advanced

List Profiles

# List all analysis profiles (IDs, literacy, display names)
copinance profile list

Get Profile

# Show details for a specific profile by ID
copinance profile get <profile-id>

Get Current Profile

# Show the profile currently used for analyze (if set)
copinance profile current

Set Current Profile

# Set which profile is used by default for analyze; omit ID to clear
copinance profile set-current <profile-id>

Delete Profile

# Remove a profile; --force skips confirmation
copinance profile delete <profile-id> --force

Analyze Commands

The analyze group accepts --json (see Machine-readable output) and --stream (see Streaming question-driven output); place them before the subcommand (equity, options, macro).

Run one-off analysis. Results are saved under .copinance/results/v2/; profiles, cache, and state live under versioned subdirectories inside .copinance.

Analyze is progressive:

• Without --question, it runs deterministic analysis.
• With --question, it runs question-driven analysis and lets the model call the relevant tools.
• Use --mode auto|deterministic|question_driven when you want to force the execution style.

Multi-turn (library only): The CLI always sends one natural-language question per invocation on analyze and on root copinance "…" (or none for deterministic analyze without --question). To continue a thread with prior user/assistant turns, use AnalyzeInstrumentRequest / AnalyzeMarketRequest with conversation_history in Python — see Library — Multi-turn question-driven analysis. The CLI does not accept prior-turn transcripts.

Analyze an Equity

Run equity analysis. By default it returns deterministic instrument, quote, history, fundamentals, and summary output. Add --question to switch to tool-using question-driven analysis.

# Run deterministic equity analysis for AAPL with mid-term timeframe (default)
copinance analyze equity AAPL --timeframe mid_term
 
# Run question-driven analysis with a custom question and optional profile
copinance analyze equity AAPL --question "What are the key risks?" --timeframe long_term --profile-id <id>
 
# Stream LLM tokens during question-driven analysis (group flag before subcommand)
copinance analyze --stream equity AAPL --question "What are the key risks?"

Question-driven examples

With --question on equity analysis, the model chooses tools (quotes, history, fundamentals, regime/macro signals, and—when your environment is configured for SEC/EDGAR—public filing data). Numbers and tables come from tools; the answer explains and synthesizes.

Illustrative questions you can ask (wording may vary):

• Market + fundamentals: “How has MSFT traded over the last quarter versus its headline revenue trend?”
• Filings: “What 10-K and 10-Q filings did Apple file recently, and what are the accession numbers?”
• Filing text: “Summarize risk factors from Apple’s latest annual filing.” (requires CIK/accession from a filings step or your knowledge.)
• Long-run financial history: “Show multi-year revenue context for Apple.”
• Cross-company comparison: “Compare recent revenue and net income for Apple and Microsoft.”
• Segments / detail in statements: “What does the latest 10-K show for revenue breakdown dimensions?”
• Insiders: “What insider Form 4 activity has been reported for Tesla recently?”
• Institutions (13F): “What were the largest equity positions in [known filer]’s latest quarterly 13F?” (works for a filer you name—e.g. a fund or manager—not as a global screen of every holder of a stock.)
• Entity check: “Confirm CIK and industry classification for AAPL before we dig into filings.”

Use --mode question_driven to force tool-using mode even if you omit --question in edge cases, and --include-prompt to save rendered prompts with results. SEC-heavy questions need EDGAR identity configured (see Configuration — SEC EDGAR).

Options:

• --json / --stream (group, before equity): machine JSON vs. streaming tokens for question-driven runs (see sections above).
• --timeframe <timeframe>: short_term, mid_term, or long_term
• --question / -q: Optional natural-language question
• --mode <mode>: auto, deterministic, or question_driven
• --profile-id <id>: Profile ID for context
• --include-prompt: Include rendered prompts in saved results for question-driven runs

Analyze Options

Run options analysis. By default it returns deterministic options-chain output (one expiry unless you repeat -e / --expiration). Add --question to let the AI fetch and interpret the relevant options and market data.

# Run deterministic options analysis for AAPL (default expiration/side)
copinance analyze options AAPL
 
# Deterministic analysis for puts expiring 2026-06-19, short-term focus
copinance analyze options AAPL --expiration 2026-06-19 --side put --timeframe short_term
 
# Question-driven analysis: AI uses options and market tools to answer the question
copinance analyze options AAPL --question "What does skew say about sentiment?" --expiration 2026-06-19
 
# Multiple expiries in one run (repeat the flag; merged, deduplicated)
copinance analyze options AAPL -e 2026-06-19 -e 2026-09-18
copinance analyze options SPY --question "Compare term structure" -e 2026-06-20 -e 2026-12-19

Options:

• --json / --stream (group, before options): same as equity group.
• -e / --expiration <date>: Optional expiration in YYYY-MM-DD. Repeat the flag to pass multiple dates (library: expiration_dates on AnalyzeInstrumentRequest). Omit for the provider default expiry.
• --timeframe <timeframe>: short_term, mid_term, or long_term
• --question / -q: Optional natural-language question
• --mode <mode>: auto, deterministic, or question_driven
• --profile-id <id>: Profile ID for context
• --include-prompt: Include rendered prompts in saved results for question-driven runs

Macro + Market Regime

Run market regime analysis: VIX, market breadth, sector rotation, and (optionally) rates, credit, commodities, and other macro indicators. Deterministic runs compute all enabled indicators; with --question the AI uses the same tools to answer in natural language.

What gets fetched

• --market-index (e.g. SPY, QQQ, DIA, IWM) is the reference index. It is used for:
  • Trend and volatility regime detection (that index’s price history).
  • The “market” benchmark when comparing sectors (breadth and rotation are relative to this index).
• VIX (^VIX) and the 11 S&P sector ETFs (XLK, XLE, XLI, XLV, XLF, XLP, XLY, XLU, XLB, XLC, XLRE) are always fetched when VIX, market breadth, or sector rotation are enabled. They are the same for any --market-index; only the reference used for comparison changes.

So when you run copinance analyze macro --market-index QQQ, the process fetches QQQ (reference), all 11 sector ETFs (for breadth/rotation), and VIX. That is expected.

Examples

# Run deterministic macro/market regime analysis (default: SPY, 252-day lookback)
copinance analyze macro
 
# Use QQQ as the reference index and 90-day lookback (sector ETFs and VIX still fetched)
copinance analyze macro --market-index QQQ --lookback-days 90
 
# Shorter lookback; DIA as reference
copinance analyze macro --market-index DIA --lookback-days 60
 
# Question-driven: AI uses macro and market tools to answer
copinance analyze macro --question "Is this a risk-on or risk-off regime?"
 
# Question-driven: combine regime signals with a macro framing question
copinance analyze macro --question "Do breadth and VIX support a defensive posture?"
 
# Question-driven with streaming LLM output
copinance analyze --stream macro --question "Is this risk-on or risk-off?"
 
# Only VIX and breadth, no sector rotation; SPY as reference
copinance analyze macro --no-include-sector-rotation

Options:

• --json / --stream (group, before macro): same as other analyze subcommands.
• --market-index / -m: Reference index for trend/volatility and sector comparison (SPY, QQQ, DIA, IWM). Breadth and rotation always use the 11 S&P sector ETFs and VIX.
• --timeframe: short_term, mid_term, or long_term (default: mid_term)
• --question / -q: Optional natural-language question (enables question-driven mode in auto)
• --mode: auto, deterministic, or question_driven
• --lookback-days: Lookback window in days (default: 252)
• --include-vix / --no-include-vix: Include VIX (default: on)
• --include-market-breadth / --no-include-market-breadth: Include market breadth (default: on)
• --include-sector-rotation / --no-include-sector-rotation: Include sector rotation (default: on)
• --include-rates, --include-credit, --include-commodities, etc.: Toggle other macro indicator groups
• --profile-id: Profile ID for context
• --include-prompt: Include rendered prompts in saved results for question-driven runs

Cache Commands

Copinance OS caches tool results (quotes, history, options chain, etc.) and stores instrument data. Cache reduces API calls and speeds up repeated requests.

Clear Cache

Clears cached tool data and stored instrument/market data (under versioned paths .copinance/cache/v2/ and .copinance/data/v2/). Does not clear profiles or analysis results.

# Clear all tool cache and stored instrument/market data
copinance cache clear
 
# Clear only quote cache entries
copinance cache clear --tool get_market_quote
 
# Clear only options chain cache entries
copinance cache clear --tool get_options_chain

Options:

• --tool <name>: Clear cache for a specific tool only (e.g. get_market_quote, get_historical_market_data, get_options_chain)

Refresh Cache

Delete a specific cache entry so the next call fetches fresh data.

# Invalidate cached quote for AAPL; next quote call will fetch live
copinance cache refresh get_market_quote --arg symbol=AAPL
 
# Invalidate options chain cache for SPY at given expiration
copinance cache refresh get_options_chain --arg underlying_symbol=SPY --arg expiration_date=2026-06-19
 
# Invalidate historical data cache for symbol and date range
copinance cache refresh get_historical_market_data --arg symbol=AAPL --arg start_date=2026-01-01 --arg end_date=2026-03-14 --arg interval=1d

Options:

• --arg key=value: Cache parameter (repeat for multiple). Must match the tool’s cache key (e.g. symbol, underlying_symbol, expiration_date). For get_options_chain, a multi-expiry agent call stores expiration_dates (list) in the key—refresh with the same argument shape the tool used.

Cache Information

# Show cache backend, tool cache path, and stored data path
copinance cache info

Shows backend, tool cache directory, and stored data directory.

All CLI data is stored under the .copinance folder (or COPINANCEOS_STORAGE_PATH) using versioned subdirectories: data/v2, cache/v2, results/v2, state/v2.

Getting Help

# Main help and list of commands
copinance --help
 
# Show version
copinance version
 
# Subcommand help (options and usage for each group)
copinance market --help
copinance profile --help
copinance analyze --help
copinance cache --help