The-Ouroboros/docs/commands.md

Command Reference

Common Command Failures

Critical: Learn from failures. Never repeat the same failed command without modification.

tea CLI (Gitea Command Line Tool)

❌ TTY Error - Interactive Confirmation Fails

~/bin/tea issues create --repo X --title "Y" --description "Z"
# Error: huh: could not open a new TTY: open /dev/tty: no such device or address

💡 Reason: tea tries to open /dev/tty for interactive confirmation prompts, which is unavailable in non-interactive environments.

✅ Solution: Use YES="" environment variable to bypass confirmation

YES="" ~/bin/tea issues create --repo jihoson/The-Ouroboros --title "Title" --description "Body"
YES="" ~/bin/tea issues edit <number> --repo jihoson/The-Ouroboros --description "Updated body"
YES="" ~/bin/tea pulls create --repo jihoson/The-Ouroboros --head feature-branch --base main --title "Title" --description "Body"

📝 Notes:

• Always set default login: ~/bin/tea login default local
• Use --repo jihoson/The-Ouroboros when outside repo directory
• tea is preferred over direct Gitea API calls for consistency

❌ Wrong Parameter Name

tea issues create --body "text"
# Error: flag provided but not defined: -body

💡 Reason: Parameter is --description, not --body.

✅ Solution: Use correct parameter name

YES="" ~/bin/tea issues create --description "text"

Gitea API (Direct HTTP Calls)

❌ Wrong Hostname

curl http://gitea.local:3000/api/v1/...
# Error: Could not resolve host: gitea.local

💡 Reason: Gitea instance runs on localhost:3000, not gitea.local.

✅ Solution: Use correct hostname (but prefer tea CLI)

curl http://localhost:3000/api/v1/repos/jihoson/The-Ouroboros/issues \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"...", "body":"..."}'

📝 Notes:

• Prefer tea CLI over direct API calls
• Only use curl for operations tea doesn't support

Git Commands

❌ User Not Configured

git commit -m "message"
# Error: Author identity unknown

💡 Reason: Git user.name and user.email not set.

✅ Solution: Configure git user

git config user.name "agentson"
git config user.email "agentson@localhost"

❌ Permission Denied on Push

git push origin branch
# Error: User permission denied for writing

💡 Reason: Repository access token lacks write permissions or user lacks repo write access.

✅ Solution:

1. Verify user has write access to repository (admin grants this)
2. Ensure git credential has correct token with write:repository scope
3. Check remote URL uses correct authentication

Python/Pytest

❌ Module Import Error

pytest tests/test_foo.py
# ModuleNotFoundError: No module named 'src'

💡 Reason: Package not installed in development mode.

✅ Solution: Install package with dev dependencies

pip install -e ".[dev]"

❌ Async Test Hangs

async def test_something():  # Hangs forever
    result = await async_function()

💡 Reason: Missing pytest-asyncio or wrong configuration.

✅ Solution: Already configured in pyproject.toml

[tool.pytest.ini_options]
asyncio_mode = "auto"

No decorator needed for async tests.

Build & Test Commands

# Install all dependencies (production + dev)
pip install -e ".[dev]"

# Run full test suite with coverage (551 tests across 25 files)
pytest -v --cov=src --cov-report=term-missing

# Run a single test file
pytest tests/test_risk.py -v

# Run a single test by name
pytest tests/test_brain.py -k "test_parse_valid_json" -v

# Lint
ruff check src/ tests/

# Type check (strict mode, non-blocking in CI)
mypy src/ --strict

# Run the trading agent
python -m src.main --mode=paper

# Run with dashboard enabled
python -m src.main --mode=paper --dashboard

# Docker
docker compose up -d ouroboros          # Run agent
docker compose --profile test up test   # Run tests in container

Dashboard

The FastAPI dashboard provides read-only monitoring of the trading system.

Starting the Dashboard

# Via CLI flag
python -m src.main --mode=paper --dashboard

# Via environment variable
DASHBOARD_ENABLED=true python -m src.main --mode=paper

Dashboard runs as a daemon thread on DASHBOARD_HOST:DASHBOARD_PORT (default: 127.0.0.1:8080).

API Endpoints

Endpoint	Description
GET /	HTML dashboard UI
GET /api/status	Daily trading status by market
GET /api/playbook/{date}	Playbook for specific date (query: market)
GET /api/scorecard/{date}	Daily scorecard from L6_DAILY context
GET /api/performance	Performance metrics by market and combined
GET /api/context/{layer}	Context data by layer L1-L7 (query: timeframe)
GET /api/decisions	Decision log entries (query: limit, market)
GET /api/scenarios/active	Today's matched scenarios

Telegram Commands

When TELEGRAM_COMMANDS_ENABLED=true (default), the bot accepts these interactive commands:

Command	Description
/help	List available commands
/status	Show trading status (mode, markets, P&L)
/positions	Display account summary (balance, cash, P&L)
/report	Daily summary metrics (trades, P&L, win rate)
/scenarios	Show today's playbook scenarios
/review	Display recent scorecards (L6_DAILY layer)
/dashboard	Show dashboard URL if enabled
/stop	Pause trading
/resume	Resume trading

Commands are only processed from the authorized TELEGRAM_CHAT_ID.

KIS API TR_ID 참조 문서

TR_ID를 추가하거나 수정할 때 반드시 공식 문서를 먼저 확인할 것.

공식 문서: docs/한국투자증권_오픈API_전체문서_20260221_030000.xlsx

⚠️ 커뮤니티 블로그, GitHub 예제 등 비공식 자료의 TR_ID는 오래되거나 틀릴 수 있음. 실제로 VTTT1006U(미국 매도 — 잘못됨)가 오랫동안 코드에 남아있던 사례가 있음 (Issue #189).

주요 TR_ID 목록

구분	모의투자 TR_ID	실전투자 TR_ID	시트명
해외주식 매수 (미국)	VTTT1002U	TTTT1002U	해외주식 주문
해외주식 매도 (미국)	VTTT1001U	TTTT1006U	해외주식 주문

새로운 TR_ID가 필요할 때:

1. 위 xlsx 파일에서 해당 거래 유형의 시트를 찾는다.
2. 모의투자(VTTT) / 실전투자(TTTT) 컬럼을 구분하여 정확한 값을 사용한다.
3. 코드에 출처 주석을 남긴다: # Source: 한국투자증권_오픈API_전체문서 — '<시트명>' 시트

Environment Setup

# Create .env file from example
cp .env.example .env

# Edit .env with your credentials
# Required: KIS_APP_KEY, KIS_APP_SECRET, KIS_ACCOUNT_NO, GEMINI_API_KEY

# Verify configuration
python -c "from src.config import Settings; print(Settings())"