The workflow described here assumes a terminal-first approach. Every step is a command. Every configuration is a file. Every action produces a log entry. This is what operating a systematic trading strategy looks like when the tooling respects the developer's workflow.

No GUI, no wizard, no dropdown menus. If that sounds familiar, you are in the right place. This guide walks through a complete cycle: from initializing a new project to connecting a live account, selecting and configuring an edge, running paper trades, and deploying to live execution.

Prerequisites

Before running the first command, confirm the following are in place:

  • Oyamori CLI installed (oyamori --version returns without error)
  • Python 3.11 environment active — Oyamori's internals depend on 3.11 specifically; other versions will produce import errors at startup
  • Alpaca account created — paper trading is sufficient to start; live credentials work identically through the same connect flow
  • ALPACA_API_KEY and ALPACA_SECRET_KEY written to a .env file in your working directory

Oyamori reads credentials from the environment at runtime. It does not store them in any other location, does not write them to the project manifest, and does not transmit them anywhere except directly to the Alpaca API. If either variable is missing when the CLI initializes, it exits immediately with a clear error rather than failing silently at the wrong moment — the order submission step.

Step 1 — Initialize a Project

oyamori init my-trading-project
cd my-trading-project

This creates the project structure:

my-trading-project/
├── oyamori.yaml        # project configuration
├── strategies/         # active strategy configs
├── logs/               # execution and trade logs
└── .env                # API credentials (not committed)

The oyamori.yaml is the project manifest — it defines which account to use, global risk limits, and which strategies are active. Everything that controls how the project behaves lives in this file or in the strategies/ directory it references.

One project maps to one Alpaca account. If you trade paper and live separately, initialize two projects. This is intentional — mixing paper and live execution within a single project is a category of error Oyamori eliminates by design. The separation is enforced at the project level, not left to a flag you might forget to set.

The logs/ directory receives structured JSON log entries for every strategy evaluation, every signal, every order submission, and every error. These logs are the audit trail. Do not delete them.

Step 2 — Connect Your Alpaca Account

oyamori account connect --broker alpaca --paper

This initiates the OAuth flow. A browser window opens, you authorize Oyamori, and the token is written back to the project. After connecting, verify the connection is healthy before doing anything else:

oyamori account status

Expected output:

Account:         paper
Status:          ACTIVE
Buying power:    $100,000.00
Portfolio value: $100,000.00
Open positions:  0

If Status is anything other than ACTIVE, do not proceed. A suspended or restricted account will accept orders and then reject them asynchronously — a failure mode that produces confusing behavior and log entries that do not match what you expected to happen. Verify account health at this step, not after a missed trade.

Step 3 — Browse the Edge Catalog

oyamori edges list

The output shows all available edges with their key parameters: regime suitability, asset class, average trade duration, and historical performance ranges. The list is filterable, so you can narrow to edges appropriate for the current market regime or a specific asset class:

oyamori edges list --regime trending
oyamori edges list --category momentum

Inspect a specific edge to understand it before deploying:

oyamori edges inspect mean-reversion-zscore

The inspect output includes the edge's mechanism description, historical performance range (Sharpe ratio, win rate, maximum drawdown), every configurable parameter with its default and allowable range, and the market regime conditions under which the edge has historically performed. Reading this output before configuring is not optional — the parameters you set in Step 4 are only meaningful if you understand what the edge is doing and why it has historically produced an advantage. Deploying an edge without reading the mechanism description is the equivalent of running a SQL query without reading the schema.

Step 4 — Configure a Strategy

oyamori strategy create mean-reversion --edge mean-reversion-zscore

This generates strategies/mean-reversion.yaml with defaults populated from the edge catalog:

name: mean-reversion
edge: mean-reversion-zscore
enabled: true

parameters:
  lookback_window: 20
  entry_zscore: 2.0
  exit_zscore: 0.5
  stop_zscore: 3.5

risk:
  max_position_pct: 0.02      # 2% of portfolio per position
  max_daily_loss_pct: 0.01    # halt if daily P&L drops 1%
  max_drawdown_pct: 0.05      # kill switch at 5% drawdown

symbols:
  - SPY
  - QQQ
  - IWM

schedule: "09:35"             # evaluate at 9:35am ET, Mon-Fri

Edit parameters directly in the file. Every change is git-committable — the entire strategy configuration is plain text, version-controllable, and reviewable in a diff. If you change entry_zscore from 2.0 to 1.8 and performance degrades, git history shows when the change was made and what preceded it.

The risk block is enforced at the execution layer, not the strategy layer. Setting max_daily_loss_pct: 0.01 means the strategy halts and closes positions if the day's P&L reaches -1%, regardless of what signal the strategy is generating at that moment. Risk limits are not suggestions; they are hard stops enforced before the strategy's own logic runs.

The schedule field controls when the strategy evaluates. For daily strategies, 09:35 — five minutes after market open — gives the opening auction time to settle. The first five minutes of trading are the noisiest period: order imbalances from overnight news clear, market makers reprice, and gaps from futures fill or extend. Evaluating at exactly 09:30 runs into this noise. The five-minute offset is not arbitrary; it is deliberate.

Step 5 — Paper Trade

Deploy to the paper account to validate the strategy behaves as expected before committing real capital:

oyamori strategy deploy mean-reversion --paper

Monitor execution in real time from a second terminal:

oyamori logs tail mean-reversion
oyamori positions list

Watch signals as they are evaluated on schedule:

oyamori signals watch mean-reversion

The signals output shows each evaluation in real time: timestamp, symbol, z-score at evaluation, action taken (enter / exit / hold), and fill price if an order was placed. This is the observable proof that the strategy is behaving mechanically and that parameters are producing evaluations you expect to see. If the signal watch shows "hold" on every evaluation when you expect entries, that is the moment to revisit the parameters — not after a month of paper trading that produces no trades and no data.

Run paper trading for a minimum of 30 completed trades before reviewing performance. Fewer trades produces statistics with confidence intervals too wide to be actionable. The winning percentage of a 10-trade sample tells you almost nothing. The winning percentage of a 50-trade sample starts to.

Step 6 — Review Paper Performance

After accumulating sufficient trade history:

oyamori strategy report mean-reversion --since 30d

The report output includes: win rate, Sharpe ratio, maximum drawdown, total trades, paper P&L, and a comparison to the historical backtest parameters shown in edges inspect. The comparison column is the important one — if live paper performance diverges significantly from backtest ranges, the cause is worth investigating before going live.

Common causes of divergence: parameter values set outside the historically tested range, symbols with different liquidity profiles than the backtest universe, or the current market regime differs from the backtest period. The report does not diagnose these automatically — it surfaces the numbers; the interpretation belongs to you.

Step 7 — Go Live

One parameter change converts the deployment from paper to live:

oyamori strategy deploy mean-reversion --live

The strategy now routes orders to the live Alpaca account. All other behavior is identical to the paper deployment. Risk parameters apply equally — the kill switch and daily loss limit enforce regardless of paper or live mode, because the enforcement is in the execution layer, not the account configuration.

There is no separate live configuration file, no live-specific parameter set, no different code path. The only difference is the account the orders route to. This is intentional: if the paper deployment behaved correctly, the live deployment should behave identically. The paper-to-live transition is a routing change, not a logic change.

Step 8 — Kill Switch

Halting a strategy mid-execution — for any reason — is a single command:

# Halt a specific strategy (close all positions, pause execution)
oyamori strategy halt mean-reversion

# Close all positions across all strategies immediately
oyamori positions close-all

# Resume a halted strategy after review
oyamori strategy resume mean-reversion

The halt command closes all positions the strategy holds before stopping execution. It does not leave open positions open while pausing. This is the correct behavior for an emergency stop: you want confirmation that the strategy is out of the market entirely, not paused mid-position while the market continues moving.

positions close-all is the broader instrument — use it when you want to exit the market completely regardless of which strategies are running. It closes every open position across every strategy in the project and logs each closure. After running it, oyamori positions list should return an empty list.

The Oyamori Approach

The workflow above is the intended operating model. Every step is inspectable — the YAML configs are readable, the logs are structured, and every action produces an audit trail. The CLI is the interface because that is the only interface that composes, scripts, and integrates cleanly with a developer's existing toolchain. Shell scripts can automate it. CI can lint the configs. Git can version every parameter change. Monitoring tools can watch the log output.

The alternative — a GUI that abstracts away configuration — produces a system where the trader cannot fully inspect what is running, cannot reproduce a configuration from a previous date, and cannot audit why a specific trade was taken. That is not an acceptable trade-off for a system that places real orders with real money.

Next: Connecting Alpaca to Your Trading Strategy →