Command-line tool (CLI)

The FinLab CLI runs through python -m finlab: sign in from the terminal, run a first backtest, ask the AI assistant, or deploy a strategy to the cloud so it runs on a schedule every day.

Install and log in

Install or update FinLab:

pip install -U finlab

Log in to your FinLab account:

python -m finlab login

Check your login status:

python -m finlab status

Run a first backtest

python -m finlab quickstart --market us

Logs in through the browser if needed, writes finlab_quickstart_us.py to the current folder, runs it, and opens finlab_quickstart_us.html. An existing script is never overwritten, so an edited version runs as it is. Without --market us it runs the Taiwan stock example, finlab_quickstart.py.

Run a strategy in the cloud every day

Deploy a strategy to the cloud, schedule daily runs, trigger manual runs, inspect execution logs, and review monthly usage.

Cloud strategy code runs in an isolated container with the FinLab SDK pre-installed. Strategy IDs must start with a letter or number, contain only letters, numbers, ., _, and -, and be at most 64 characters. Schedule times use HH:MM in the Asia/Taipei timezone.

python -m finlab login

python -m finlab cloud deploy my-strategy --code strategy.py --time 09:30 --tier s

python -m finlab cloud run my-strategy

python -m finlab cloud logs my-strategy --limit 5 --show-output

Plan limits

Cloud strategy execution limits available tiers and strategy count by plan. Use python -m finlab cloud status to view the current account's allowed tiers and execution count for the month.

When --tier is omitted, a new strategy uses the account plan's default tier. Updating an existing strategy keeps its current tier when it already has one. Free users cannot deploy cloud strategies.

Tier specs:

Deploy one file or a multi-file strategy

You can deploy a single Python file or a zip archive for multi-file strategies.

python -m finlab cloud deploy my-strategy --code strategy.py

python -m finlab cloud deploy zip-strategy --zip strategy.zip --entry-script main.py --tier m

Use exactly one of --code and --zip. Inline source code is limited to 256 KiB. Zip uploads are limited to 5 MiB compressed, 50 MiB extracted, and 100 files.

Options:

Join the contest

python -m finlab cloud deploy my-strategy --code strategy.py --time 09:30 --contest --contest-alias TeamA

Contest strategies must upload a backtest report during scheduled execution, for example with sim(..., upload=True). Manual cloud run executions do not count toward contest results.

Set how often it runs

Set a daily run time:

python -m finlab cloud schedule set my-strategy 14:30

Run weekly, monthly, or on a custom cron:

python -m finlab cloud schedule set my-strat 09:00 --frequency weekly --days-of-week 1,5
python -m finlab cloud schedule set my-strat 09:00 --frequency monthly --day-of-month 31
python -m finlab cloud schedule set my-strat --frequency custom --cron '0 9 * * 1-5'
python -m finlab cloud deploy my-strat --code strategy.py --time 09:00 --frequency weekly --days-of-week 1,5

• All schedules use Asia/Taipei without a market-holiday calendar. Missing monthly dates are skipped.
• With no frequency option, new schedules run daily and existing frequencies are preserved.
• Weekdays use 0 (Sunday) through 6 (Saturday).
• Cron accepts five numeric fields: minute, hour, day, month, weekday, with *, lists, ranges and steps. Restricted day-of-month and day-of-week fields use OR semantics.

Remove the daily schedule:

python -m finlab cloud schedule delete my-strategy

Run manually with another tier

The strategy must already be deployed. Manual triggers are rate-limited to 5 runs per strategy per hour. You can override the compute tier for this manual run only:

python -m finlab cloud run my-strategy --tier m

View execution logs

Show recent execution records for a strategy, including status, duration, and cost. Status values include queued, running, success, error, timeout, and quota_exceeded.

python -m finlab cloud logs my-strategy

List, inspect and delete strategies

List cloud strategies for the logged-in account (--limit 500 lists up to 500):

python -m finlab cloud list
python -m finlab cloud list --limit 500

Fetch metadata for one strategy. Inline strategies include source code. Zip strategies show metadata and the entry script only, because source files are stored in cloud storage:

python -m finlab cloud get my-strategy

Print only inline strategy source code, which is useful when redirecting output to a file or piping it to another tool:

python -m finlab cloud get my-strategy --code-only

Delete a strategy, metadata, code, and schedule; execution history is preserved. Add -y to skip the deletion confirmation prompt:

python -m finlab cloud delete my-strategy
python -m finlab cloud delete my-strategy -y

Check the monthly quota

Show current cloud execution usage, allowed tiers, and execution counts, or query a specific month:

python -m finlab cloud status
python -m finlab cloud status --month 2026-04

Login and credentials

Ask the AI assistant from the terminal

Ask the FinLab AI assistant from the terminal: package usage, backtest errors, data definitions, accounts and plans. It shares one conversation history and the monthly quota of 200 questions (reset at 00:00 on the 1st, Taiwan time) with the website support chat. Log in first.

Ask a question

Ask one question and wait for the answer:

python -m finlab ai "How do I get monthly revenue?"

Send an error message or code along with the question:

python my_strategy.py 2>&1 | python -m finlab ai "How do I fix this error?"

Without a question it starts a chat. Multi-line pastes are sent as one question; type exit to leave:

python -m finlab ai

Ctrl+C only stops waiting; the question is still answered.

Read earlier questions

Show the latest question and answer, waiting if it is still in progress:

python -m finlab ai --last

List the latest 10 questions, or a number you choose. The list shows each question's ID, creation time, status and a summary, newest first:

python -m finlab ai --history
python -m finlab ai --history 50

Read one question and all its replies by its ID from the list, including case progress notices added later:

python -m finlab ai --show <question-id>

--history and --show read the record as it is now, without waiting for processing to finish. They only cover the logged-in account.

Let your own agent parse the output

Add --json so your own agent can parse the result:

python -m finlab ai --history 50 --json
python -m finlab ai --show <question-id> --json
python -m finlab ai --last --json
python -m finlab ai "Where does the issue I reported stand?" --json

--history --json prints {"messages": [...]}; the other modes print one complete question object with id, text, status, createdAt, updatedAt and a replies array. The JSON keeps the full question and every reply. Asking a question and --last wait for completion before printing one JSON object, and progress messages go to stderr; do not merge stderr into stdout. Asking still counts toward the 200-question monthly quota and the minimum 10-second interval. --json needs a question or a reading option and is not for the interactive chat.

The assistant only answers FinLab questions. Accounts that keep sending unrelated or meaningless content after a reminder, or send malicious content, lose access to the assistant.

Install the FinLab skill for AI tools

python -m finlab skill install

Downloads the latest skill from finlab-ai to ~/.agents/skills/finlab, which Codex and Cursor read, and to ~/.claude/skills/finlab when Claude Code is present. Node.js is not required. Run it again to update.

Next steps