CLI quickstart

Pure CLI mode is intended for servers, SSH sessions, scripts, and CI. It runs Runtime directly and does not require the Desktop app or a browser.

1. Install

Python 3.11 or newer is required. From the repository root:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'

In Windows PowerShell:

.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Check the entry points:

scientific-agent --help
scientific-agent-bench --help

You can also run directly from source without installation:

PYTHONPATH=src python -m scientific_agent run examples/toy.yaml

2. Run the deterministic example

scientific-agent run examples/toy.yaml

The final lines should resemble:

[Metric] score = 0.93
[CriteriaEngine] Acceptance criteria satisfied
DONE run_id=run_... status=SUCCESS

Keep the run_... identifier, then inspect it:

scientific-agent status run_...
scientific-agent status run_... --events

status prints a JSON summary; --events appends readable event types and action links. Exit code 0 means the command completed successfully. run and resume return 2 when the resulting run is not SUCCESS.

3. Create now, execute later

scientific-agent new examples/toy.yaml

This writes the immutable RunCreated event and prints a Run ID. Execute it later with:

scientific-agent resume run_...

resume also recovers a run left RUNNING by a process crash and continues PAUSED, BLOCKED, CAPABILITY_MISSING, or BUDGET_EXHAUSTED runs. If a budget needs changing, write the revised limit through Desktop or Control API before resuming.

4. Choose storage locations

Global options must precede the subcommand:

scientific-agent \
  --data-dir /srv/scientific-agent/data \
  --cache-dir /srv/scientific-agent/cache \
  --config-dir /srv/scientific-agent/config \
  run examples/toy.yaml

Durable research data defaults to ~/Documents/ScientificAgent. Cache and ordinary configuration use platform cache/config directories and are kept separate from scientific data.

5. Run the tutorial plugin

The repository includes a zero-dependency, fully runnable plugin example:

scientific-agent run examples/plugin_tutorial.yaml

It calculates quality_factor=4, creates oscillator-assessment.json, and completes against quality_factor >= 3. See Build a working plugin for the full authoring walkthrough.

6. Optional scientific stacks

Install extras only for the corresponding workflows:

python -m pip install -e '.[dev,beam-xsuite]'
scientific-agent run examples/beam_xsuite.yaml

python -m pip install -e '.[dev,beam-ml]'
scientific-agent run examples/beam_ml.yaml

For real model calls, install the llm or combined extra and supply credentials through the environment. Never put API keys in YAML.

Next: CLI command reference and Research configuration.