CLI Usage

Commands below are implemented in src/cspilot/cli.py. The installed script is cspilot; cspiolt is also currently configured as a legacy alias.

General And Agent Commands

search

Purpose: answer a general natural-language question with the AGAPI-backed general agent.

cspilot search "what is chemical space?" --workdir runs/search

Output files: search_result.json in the selected workdir.

Root quoted question fallback

Purpose: route a quoted unknown root command to search.

cspilot "what is the chemical space?"

Output files: same as search.

agent

Purpose: run the direct AGAPI tool-using agent.

cspilot agent "inspect tests/examples/input.xyz" \
  --workdir runs/agent_test --agent-profile chem

Options include --model, --base-url, and --agent-profile chem|materials|general.

Output files: agent_result.json and any files generated by called tools.

plan

Purpose: create a strict JSON plan through AGAPI.

cspilot plan "inspect tests/examples/input.xyz" --workdir runs/test --profile chem

Output files: plan.json.

execute

Purpose: execute an existing JSON plan through the fixed registry.

cspilot execute runs/test/plan.json --workdir runs/test --profile chem

Output files: execution_result.json and step_###_result.json.

run

Purpose: plan, execute, verify, and report.

cspilot run "inspect tests/examples/input.xyz" \
  --workdir runs/test --profile chem --pretty

Useful flags:

cspilot run "inspect tests/examples/input.xyz" --workdir runs/test --no-pretty
cspilot run "inspect tests/examples/input.xyz" --workdir runs/test --quiet
cspilot run "Find all Al2O3 materials" --workdir runs/al2o3 --profile materials --html

Output files: plan.json, execution_result.json, verification_result.json, step_###_result.json, and final_report.md or final_report.html.

graph-run

Purpose: run the LangGraph planner/executor/verifier/reporter loop.

Single mode:

cspilot graph-run "inspect tests/examples/input.xyz" \
  --workdir runs/water --profile chem --agent-mode single

Multi mode with routing:

cspilot graph-run "Find all Al2O3 materials" \
  --profile auto --agent-mode multi --html --workdir runs/al2o3

Useful flags: --agent-mode single|multi, --profile, --html, --pretty/--no-pretty, --quiet, --max-retries.

Output files: plan.json, execution_result.json, verification_result.json, final_state.json, final_report.md/html, and route.json in multi mode.

docs-check

Purpose: run lightweight documentation consistency checks.

cspilot docs-check

Output files: none; exits nonzero when checks fail.

Deterministic Calculation Commands

inspect

cspilot inspect tests/examples/input.xyz

Purpose: inspect an XYZ with ASE.

Output files: timestamped run directory with copied input and result.json.

xtb-opt

cspilot xtb-opt tests/examples/input.xyz --charge 0 --uhf 0

Purpose: run xTB geometry optimization.

Output files: result.json, copied input, and xTB outputs such as xtbopt.xyz and xtbopt.log when xTB succeeds.

orca-sp

cspilot orca-sp tests/examples/input.xyz \
  --method r2scan-3c --basis def2-SVP --charge 0 --mult 1

Purpose: run ORCA calculations.

Output files: result.json, ORCA input/output files such as job.inp and job.out when ORCA runs.

mace-opt

cspilot mace-opt tests/examples/input.xyz --model /path/to/model.model

Purpose: run MACE geometry optimization.

Output files: result.json, and on success MACE optimized geometry, trajectory, and log files.

stk Commands

Top-level shortcuts

cspilot stk-build-smiles "c1ccccc1" --workdir runs/stk_benzene
cspilot stk-polymer "BrCCBr" --repeating-unit A --num-repeating-units 4 --workdir runs/stk_polymer
cspilot stk-xtb "c1ccccc1" --workdir runs/stk_xtb --charge 0 --uhf 0

Output files: JSON results, molecule files such as .mol/.xyz, and for stk-xtb a workflow_result.json plus xTB outputs when xTB runs.

stk building-block-smiles

cspilot stk building-block-smiles "c1ccccc1" runs/stk/benzene.mol

Purpose: build an stk building block from SMILES.

stk building-block-file

cspilot stk building-block-file runs/stk/benzene.mol --output-path runs/stk/copy.mol

Purpose: load an stk building block from a file and optionally export it.

stk linear-polymer

cspilot stk linear-polymer "BrCCBr" A 4 runs/stk/polymer.mol

Purpose: construct a linear polymer.

stk replace-smiles

cspilot stk replace-smiles "c1ccccc1" "[H]" "F" runs/stk/fluoro.mol

Purpose: edit a molecule with RDKit substructure replacement.

stk export-xyz

cspilot stk export-xyz runs/stk/benzene.mol runs/stk/benzene.xyz

Purpose: export molecule files to XYZ using stk/RDKit fallback.

NWPESSe And GreenCatAI

nwpesse-search

cspilot nwpesse-search "(h2o)4Mg" \
  --workdir runs/h2o4mg --max-calculations 10 --box-size 3.0

Purpose: prepare and run a fragment-cluster global-minimum search.

Output files: mol.cluster, mol.inp, workflow_result.json, NWPESSe stdout/stderr, candidate XYZ files, and lowest_energy.xyz when found.

greencatai design-mbh

cspilot greencatai design-mbh --output-dir runs/mbh_api \
  --search-space configs/search_space.json --scoring configs/scoring.json

Purpose: call the installed GreenCatAI MBH catalyst-design API.

Output files: GreenCatAI artifacts in the selected output directory and a JSON tool result.

Fixed Workflows

cspilot workflow xtb-orca-sp tests/examples/input.xyz --charge 0 --mult 1
cspilot workflow xtb-orca-freq tests/examples/input.xyz --charge 0 --mult 1
cspilot workflow mace-orca tests/examples/input.xyz --model /path/to/model.model

Output files: timestamped workflow directory with workflow_result.json and step subdirectories.