1. Write code? Run it. Use Bash to execute Python via

   uv run

   . Don't dump code blocks and walk away.
2. Generate files? Open them. After saving a chart/report, run

   open <filepath>

   (macOS) or equivalent.
3. Fetch data? Show it. Print the actual numbers. Users came for insights, not import statements.
4. Error occurs? Fix it. Don't report the error and stop. Debug, retry, solve.
5. Missing dependencies? Install them. Use

   uv pip install <package>

   — never ask the user to install manually.

"Talk is cheap. Show me the code results."

1. uv is installed (Python package manager):
   bash

   uv --version || curl -LsSf https://astral.sh/uv/install.sh | sh

   After installing, ensure

   uv

   is on PATH:
   bash

   source $HOME/.local/bin/env 2>/dev/null  # Add uv to current shell

2. FinLab is installed via uv:
   bash

   uv python install 3.12  # Ensure Python is available (skip if already installed)
   uv pip install --system finlab python-dotenv 2>/dev/null || uv pip install finlab python-dotenv

   Or use

   uv run

   for zero-setup execution (recommended for one-off scripts):
   bash

   uv run --with finlab --with python-dotenv python3 script.py

   uv run --with

   auto-creates a temporary environment with dependencies — no venv management needed.
3. API Token is set (required - finlab will fail without it):
   bash

   echo $FINLAB_API_TOKEN

   If empty, check for

   .env

   file first:
   bash

   cat .env 2>/dev/null | grep FINLAB_API_TOKEN

   If

   .env

   exists with token, load it in Python code:
   python

   from dotenv import load_dotenv
   load_dotenv()  # Loads FINLAB_API_TOKEN from .env
   
   from finlab import data
   # ... proceed normally

   If no token anywhere, authenticate the user:
   bash

   # 1. Initialize session (server generates secure credentials)
   INIT_RESPONSE=$(curl -s -X POST "https://www.finlab.finance/api/auth/cli/init")
   SESSION_ID=$(echo "$INIT_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
   POLL_SECRET=$(echo "$INIT_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['pollSecret'])")
   AUTH_URL=$(echo "$INIT_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['authUrl'])")
   
   # 2. Open browser for user login
   open "$AUTH_URL"

   Tell user: "Please click 'Sign in with Google' in the browser."
   bash

   # 3. Poll for token with secret and save to .env
   for i in {1..150}; do
     RESULT=$(curl -s "https://www.finlab.finance/api/auth/poll?s=$SESSION_ID&secret=$POLL_SECRET")
     if echo "$RESULT" | grep -q '"status":"success"'; then
       TOKEN=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
       export FINLAB_API_TOKEN="$TOKEN"
       echo "FINLAB_API_TOKEN=$TOKEN" >> .env
       grep -q "^\.env$" .gitignore 2>/dev/null || echo ".env" >> .gitignore
       echo "Login successful! Token saved to .env"
       break
     fi
     sleep 2
   done

• Resets daily at 8:00 AM Taiwan time (UTC+8)
• When limit exceeded, user must wait for reset or upgrade to VIP

Usage exceed 500 MB/day

1. Daily quota reached (Free: 500 MB)
2. Auto-resets at 8:00 AM Taiwan time
3. VIP offers 5000 MB (10x increase)
4. Upgrade link: https://www.finlab.finance/payment

• All strategy code examples use Traditional Chinese (繁體中文) variable names where appropriate
• This package is specifically designed for Taiwan stock market (TSE/OTC)
• Data frequency varies: daily (price), monthly (revenue), quarterly (financial statements)
• Always use

  sim(..., upload=False)

  for experiments,

  upload=True

  only for final production strategies