CLI Usage

Independent multi-agent and Multiwfn options

run, bare prompts, and graph-run accept --multiagent (alias --multi-agent) and --workers 1..4. Default remains a single agent; child loops default to serial execution. This is separate from legacy --agent-mode multi specialist routing. See scope, examples and artifacts.

cspilot multiwfn FILE --analysis mulliken|hirshfeld|mayer --workdir runs/multiwfn runs deterministic local analysis without an API key. Pass an existing GBW, Molden or FCH file. It prints parsed JSON and persists logs, menu input and results.

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 configured OpenAI-compatible backend. OpenRouter is the recommended default when OPENROUTER_API_KEY is set.

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 natural-language request to the tool-using run agent.

cspilot "what is the chemical space?"

Output files: same as run. Use explicit search for general explanations that do not require tools.

agent

Purpose: run the direct tool-using agent through the configured model backend.

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 the configured model backend.

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

Useful flags: --profile, --model, and --base-url.

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: iteratively choose a tool, observe its result, decide the next action, then verify and report.

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

Useful flags: --model, --base-url, --html, --pretty/--no-pretty, --quiet, --max-steps, and --max-retries.

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 "inspect tests/examples/input.xyz and print its formula" --workdir runs/water-html --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 agent loop with optional specialist routing.

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 "inspect tests/examples/input.xyz" \
  --profile auto --agent-mode multi --html --workdir runs/inspection

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

Both commands default to 8 tool actions and 1 recovery attempt after a failed or unverified action. Returned answers print unless quiet mode is selected. Full diagnostics remain in the saved report. HTML saving still prints the answer.

Output files: plan.json, execution_result.json, verification_result.json, final_state.json, final_report.md/html, and route.json in multi mode. Each decision and tool attempt also produces decision_NNN.json, step_NNN_result.json, and cumulative observations.json.

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 "O" --workdir runs/stk_water
cspilot stk-polymer "BrCCBr" --repeating-unit A --num-repeating-units 4 --workdir runs/stk_polymer
cspilot stk-xtb "O" --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 "O" runs/stk/water.mol

Purpose: build an stk building block from SMILES.

stk building-block-file

cspilot stk building-block-file runs/stk/water.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/water.mol runs/stk/water.xyz

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

NWPESSe

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.

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.