CLI Reference

Complete guide to using the Copinance OS command-line interface.

Running Commands

After installation:

copinance <command>

Without installation:

python -m copinanceos.cli <command>

Stock Commands

Search Stocks

Search for stocks by symbol or company name.

copinance stock search "Apple"
copinance stock search "AAPL" --limit 5

Options:

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

Profile Commands

Profiles customize research output based on your financial literacy level.

Note: When you run research commands (create, run, execute, ask) without a profile, the system will automatically prompt you to set your financial literacy level for more personalized analysis results.

Create Profile

copinance profile create --literacy intermediate --name "My Profile"

Literacy levels: beginner, intermediate, advanced

List Profiles

copinance profile list

Get Profile

copinance profile get <profile-id>

Get Current Profile

copinance profile current

Shows the currently active profile (if any).

Set Current Profile

copinance profile set-current <profile-id>

Set a profile as the current default. Omit the profile ID to clear the current profile.

Delete Profile

copinance profile delete <profile-id> --force

Research Commands

Copinance OS provides three separate commands for research management: create, execute, and run. Understanding when to use each helps you work more efficiently.

Why Three Separate Commands?

create - Creates a research task without executing it

• Use when: You want to prepare research tasks in advance, schedule them, or set up multiple research tasks before running them
• Returns: A research ID that you can use later
• Example: Create research tasks for multiple stocks, then execute them in batch

execute - Executes an existing research (by ID)

• Use when: You want to re-run existing research, execute research created earlier, or run the same research with different contexts/questions
• Allows: Multiple executions of the same research with different parameters
• Example: Re-analyze a stock with a new question or updated context

run - Convenience command that creates AND executes in one step

• Use when: You want quick one-off analyses without managing research lifecycle
• Best for: Quick testing, exploratory analysis, or when you don’t need to save/reuse the research
• Example: Quick analysis during market hours

Create Research

Create a new research task without executing it.

copinance research create AAPL --workflow static --timeframe mid_term

Options:

• --workflow <type>: static, agentic, or fundamentals (default: static)
• --timeframe <timeframe>: short_term, mid_term, or long_term (default: mid_term)
• --profile-id <id>: Profile ID for context (optional)

Note: If no profile is provided and you don’t have a current profile, you’ll be prompted to set your financial literacy level for personalized analysis.

Use Cases:

• Prepare research tasks in advance
• Create multiple research tasks for batch processing
• Set up research with specific configurations before execution
• Schedule research for later execution

Execute Research

Execute an existing research by ID. Can be called multiple times with different contexts.

copinance research execute <research-id>
copinance research execute <research-id> --question "What is the P/E ratio?"

Options:

• --question <question>: Custom question for agentic workflows (optional)

Note: If the research doesn’t have a profile associated, you’ll be prompted to set your financial literacy level for personalized analysis.

Use Cases:

• Re-run research with updated data
• Execute research created earlier
• Run the same research with different questions/contexts
• Re-analyze stocks as new data becomes available

Run Research (Quick)

Create and execute a research workflow in one command. Convenience method for quick analysis.

copinance research run AAPL --workflow static
copinance research run AAPL --workflow agentic --question "Analyze this stock"

Options:

• --workflow <type>: static, agentic, or fundamentals (default: static)
• --timeframe <timeframe>: short_term, mid_term, or long_term (default: mid_term)
• --profile-id <id>: Profile ID for context (optional)
• --question <question>: Custom question for agentic workflows (optional)

Note: If no profile is provided and you don’t have a current profile, you’ll be prompted to set your financial literacy level for personalized analysis.

Use Cases:

• Quick one-off analysis
• Exploratory research
• Testing workflows
• When you don’t need to manage research lifecycle

Get Research

View research details and results.

copinance research get <research-id>

Ask Question (Agentic)

Quick Q&A using agentic workflow. Can ask questions about specific stocks or market-wide questions.

Stock-specific questions:

copinance research ask "What is the current price and P/E ratio?" --symbol AAPL
copinance research ask "What are the key risks for this stock?" --symbol TSLA

Market-wide questions (no symbol needed):

copinance research ask "What is the current market sentiment and which sectors are leading?"
copinance research ask "What is the current VIX level and market fear sentiment?"

Options:

• --symbol <symbol> or -s <symbol>: Stock symbol (optional for market-wide questions)
• --timeframe <timeframe>: short_term, mid_term, or long_term (default: mid_term)
• --profile-id <id>: Profile ID for context (optional)

Note:

• Requires LLM provider configuration (Gemini API key or Ollama setup) - see Configuration
• If no profile is provided and you don’t have a current profile, you’ll be prompted to set your financial literacy level for personalized analysis
• For market-wide questions, omit the --symbol option

Set Research Context

Associate a profile with research.

copinance research set-context <research-id> --profile-id <profile-id>

Examples

Basic Workflow

# 1. Search for a stock
copinance stock search "Apple"
 
# 2. Create a profile
copinance profile create --literacy intermediate --name "Trader"
 
# 3. Run research
copinance research run AAPL --workflow static --timeframe mid_term

Agentic Workflow

# Ask a stock-specific question (requires LLM provider configuration)
copinance research ask "What are the key risks for this stock?" --symbol AAPL
 
# Market regime analysis for a stock
copinance research ask "What is the current market trend and volatility regime?" --symbol AAPL
 
# Market-wide questions (no symbol needed)
copinance research ask "What is the current market sentiment and which sectors are leading?"
copinance research ask "What is the current VIX level and market fear sentiment?"
 
# Combined stock and market analysis
copinance research ask "Analyze this stock's regime and compare it to broader market conditions" --symbol AAPL

Research Management

# Create research
copinance research create MSFT --workflow static
 
# Execute later
copinance research execute <research-id>
 
# View results
copinance research get <research-id>

Cache Commands

Copinance OS includes a built-in caching system to reduce API calls and improve performance.

Clear Cache

Clear cached tool data:

# Clear all cache
copinance cache clear
 
# Clear cache for a specific tool
copinance cache clear --tool <tool-name>

Refresh Cache

Refresh (delete) cache for a specific tool to force fresh data on next call:

# Refresh cache for a tool
copinance cache refresh <tool-name>
 
# Refresh cache for a tool with a specific symbol
copinance cache refresh <tool-name> --symbol AAPL

Cache Information

View cache configuration and status:

copinance cache info

This shows:

• Cache backend type
• Cache directory location

Getting Help

copinance --help
copinance research --help
copinance profile --help
copinance cache --help