Command-line interface¶

The chemgraph command provides query execution, evaluation, session inspection, model discovery, the web interface, dashboards, and Academy orchestration.

chemgraph run        Run an agent query or interactive session
chemgraph eval       Evaluate a dataset
chemgraph session    List, inspect, or delete saved sessions
chemgraph models     List registered model identifiers
chemgraph ui         Launch the Streamlit web interface
chemgraph dashboard  Launch the trace dashboard
chemgraph academy    Run Academy campaigns and workers

Use chemgraph <command> --help for the options supported by your installed version.

Run a query¶

chemgraph run \
  --model gpt-4o-mini \
  --workflow single_agent \
  --query "Build methane and optimize it with EMT."

Common options:

Option	Meaning
`-q`, `--query`	Natural-language request
`-m`, `--model`	Provider/model identifier
`--reasoning-effort`	Reasoning effort for a supported model
`-w`, `--workflow`	Agent workflow; defaults to `single_agent`
`-o`, `--output`	Full `state` or `last_message`
`-s`, `--structured`	Request a structured final response
`-r`, `--report`	Enable HTML report generation
`--human-supervised`	Allow supported tools to pause for confirmation
`--recursion-limit`	Maximum graph steps; defaults to 200
`--output-file`	Save the printed result to a file
`--result-file PATH`	Write a JSON session receipt (headless `main_agent`)
`--answers-file PATH`	Submit clarification answers by interrupt ID with `--resume`
`-v`, `-vv`	INFO or DEBUG diagnostics

The recursion limit counts graph steps, including middleware and tool execution, not just model calls. Raising it allows longer workflows; it does not reduce token consumption. Explicit configuration and saved session limits are retained.

After each query, the CLI prints provider-reported token usage locally. Non-interactive runs send usage lines to stderr, including failures and cancellation, so usage does not appear in captured stdout. Interactive runs display usage alongside the conversation.

Tokens: 12,340 input · 520 output · 12,860 total

This is the total for that user turn, including all model calls, delegated workers, and approval continuations. /retry adds to the same turn's total. Input includes conversation history sent on each call, so these counts are not the size of a single context window. Cached input and reasoning output are labeled separately when reported and are already included in input/output. Missing usage is displayed as unavailable or partial, never assumed to be zero.

On leaving interactive mode with /quit or EOF, Session tokens: reports the recorded totals for the sessions used in that CLI process, including any restored session history. Model/workflow switches retain the earlier session's counts. Ctrl+C during a query prints the available turn counts and keeps the REPL open. Failed queries also retain their reported usage.

These lines use numeric counters already returned by the provider. They make no additional model requests and are not inserted into the conversation or saved answer. Usage is persisted per call in the existing session database when memory is enabled. Older sessions have no reconstructed usage for their historical calls. Their session totals remain partial after new calls are recorded, with an explicit historical-usage note; entirely unaccounted history displays unavailable. Rejected operations that fail validation do not print or alter a previous turn's usage.

The CLI configures logging to stop propagation at the chemgraph logger to avoid duplicate output. Applications embedding the CLI should attach handlers to that namespace if they need its records; Python root handlers will not receive them after CLI logging configuration. Library use alone does not configure this.

The legacy no-subcommand form, such as chemgraph -q "...", remains supported, but new scripts should use chemgraph run.

Reasoning effort¶

Verified Argo GPT-5.6 and Claude models accept an explicit reasoning effort:

chemgraph run \
  --model argo:claude-opus-4.8 \
  --reasoning-effort xhigh \
  --query "Analyze the reaction mechanism."

The GPT-5.6 routes accept none, low, medium, high, xhigh, and max. The Claude Opus 4.8, Opus 5, Opus 5.5, Sonnet 5.5, and Haiku 5.5 routes accept low, medium, high, xhigh, and max. Both model families default to medium. Claude effort controls overall response work through Anthropic's output_config.effort; it does not make ChemGraph explicitly enable adaptive thinking. The Claude 5.5 models think by default, and that thinking counts toward the response token limit.

Validate credentials¶

chemgraph models
chemgraph run --model gpt-4o-mini --check-keys

The check validates configuration; it does not prove that every external calculator, database, or facility endpoint is reachable.

Interactive mode¶

chemgraph run --interactive

Use /help inside the shell to see the commands available in your release. Interactive sessions preserve conversation context and can be resumed later.

The main_agent workflow is a durable agent with direct skills, file/shell, and local chemistry tools plus optional delegation. Interactive use reviews actions by default:

chemgraph run --interactive --workflow main_agent --workspace . \
  --skill ../shared-skills --subagent single_agent --subagent deep_agent

Omit --subagent to expose the built-in specialist catalog with no active worker. A selection restricts discovery. The agent loads specialists on demand before delegation; loading lasts for one turn, including pending approvals and restart. --tool NAME restricts the lazy catalog, and --no-discover-skills disables personal/project discovery. The corresponding TOML keys are workspace, skills, subagents, tools, and discover_skills; CLI lists replace TOML lists.

Direct main-agent and attributed worker tool calls are printed as they start. Without --workspace, file tools read and write checkpoint-backed files and no shell is exposed. With a workspace, /workspace/ maps to that host directory. Registry tools run on the host independently of this backend; use absolute host paths for registry artifacts. The shell is not confined to the workspace. File mutations, shell commands, and reviewed registry operations pause for review.

Start a new session after the capabilities upgrade. Old transcripts remain readable; old checkpoints cannot resume through the new graph. New supported CLI configurations restore through startup --resume ID or /resume ID, including pending approvals. Custom Python configurations require Python reconstruction. Both resume entry points display the saved workspace, skills, workers, and tool catalog before host-access confirmation. Saved graph settings take precedence over current CLI flags and TOML settings; changing them requires a new session. The Python REPL removal also changes the catalog and approval policy: sessions created before these combined upgrades require a new session. Their transcripts remain readable.

The development workspace Deep Agent can execute broad filesystem and shell actions. Call it directly with action reviews:

chemgraph run --interactive --workflow deep_agent \
  --deepagent-workspace /path/to/disposable-checkout

Interactive Deep Agent startup uses the current directory when --deepagent-workspace is omitted. Before enabling it, the confirmation panel shows the resolved workspace and explains that shell commands can access the host beyond that directory. Declining leaves the capability disabled. Headless runs still require an explicit workspace and the approval-skip flag.

Or add the same graph to the supervisor as the legacy deep_agent worker:

chemgraph run --interactive --workflow main_agent --deepagent \
  --deepagent-workspace /path/to/disposable-checkout \
  --deepagent-skill ../external/AtomisticSkills/.agents/skills/

The direct interactive workflow keeps one process-local thread until the model or workflow changes. It is not restored across CLI processes. Shell and file mutations use structured approve/reject prompts.

At each action review, press Enter to approve the displayed action. You can also enter 1, y, yes, a, or approve. To reject it, enter 2, n, no, r, or reject. These shortcuts are case-insensitive.

For a shortened preview, enter v or view to inspect the full action in a pager, then return to the same decision. Viewing does not approve the action. Type any other nonempty text to skip that action and give the agent feedback, for example Use EMT instead of MACE for this test. The agent receives your instructions and can propose a revised action, which is reviewed normally. Each action in a batch is reviewed separately; feedback does not discard other decisions. Custom policies expose only the permitted choices; Enter approves only when approval is allowed. Ctrl+C and EOF do not submit a decision.

Reviews show multiline commands, file content, and proposed replacement snippets. Terminal control characters are displayed as visible escapes. Large previews retain their head and tail within 40 source lines and 8,000 characters, with an omission notice and access to the complete arguments through v. Replacement diffs use the requested before/after text, not a read of the current file, and flag replacements that apply to all occurrences. Pending terminal input is cleared before each decision where supported, so an Enter queued during earlier work does not approve the next action. Redirected input is preserved. The startup host-access confirmation is separate from these per-action reviews.

Auto mode. In an interactive deep_agent or main_agent chat, /auto on (after a confirmation) or answering 3 / auto at a review approves every later tool action without asking, including actions from main-agent workers. Each action's preview is still printed with an Auto-approved line, and the prompt shows ChemGraph [auto]. Questions from the agent are still asked, and actions whose policy does not allow approval are still reviewed. After 50 auto-approved actions in a row, the next action is reviewed, and your answer starts a new run. Actions that were already pending in a session restored with /resume are always reviewed. /auto off restores reviews; /auto and /config show the current state. Auto mode lasts until /auto off or exit, including across /model, /workflow, and /resume. It is never saved with a session, so restored sessions keep their reviewed approval mode and every new launch starts with reviews on. Unlike --dangerously-skip-approvals, it does not skip the startup host-access confirmation.

The selected directory is mounted for file tools at /workspace. Thus, --deepagent-workspace test/ makes /workspace/example.py refer to test/example.py, not test/workspace/example.py. Shell execution uses the absolute host-path mapping supplied to the model. Existing files under a previously created test/workspace/ directory are not migrated.

Bundled chemgraph and pbs-hpc skills load automatically, followed by ~/.chemgraph/skills/ and the workspace's .agents/skills/ when present. Skill paths are resolved against the CLI invocation directory, independently of --deepagent-workspace. Absolute paths, ~, and ../ paths work automatically without copies or symlinks. Old CLI /workspace/... examples must be replaced with host paths; agent file tools continue to use virtual workspace paths.

Repeat --deepagent-skill PATH to add host directories; later sources win for matching skill names. --no-deepagent-discover-skills disables personal and project discovery while retaining bundled and explicit sources.

Each source contains a directory per skill with a SKILL.md and name and description YAML frontmatter. Metadata refreshes at each new turn, including on reconstructed graphs. Bundled resources are read-only; templates/helpers must be copied into the execution filesystem before use by the shell. Normal file mutation and execution approvals apply. See skills.

Deep Agent run logs use the normal ChemGraph locations rather than the selected workspace. The default is cg_logs/session_* for state JSON plus the configured session database. Pending approval state and the final resumed state are both recorded.

For automation, headless execution must opt out of those prompts explicitly:

chemgraph run --workflow deep_agent \
  --deepagent-workspace /path/to/disposable-checkout \
  --deepagent-skill ../external/AtomisticSkills/.agents/skills/ \
  --deepagent-dangerously-skip-approvals \
  --query "Run the repository tests and summarize failures."

The legacy flag above remains limited to non-interactive deep_agent with an explicit workspace. The shared --dangerously-skip-approvals flag supports both main_agent and deep_agent, interactively or headlessly. Neither flag is read from TOML. Bypass also skips host-access confirmation; the host-access notice remains visible. Interactive bypass uses the selected model and workflow without startup selection prompts. /config displays the mode.

chemgraph run -w main_agent --workspace . --dangerously-skip-approvals \
  -q "Run the repository tests and summarize failures."
chemgraph run --interactive -w main_agent --dangerously-skip-approvals \
  --resume <session-id>

For main_agent, omitting --workspace still means checkpoint files and no shell; local registry tools can still access the host. Headless standalone deep_agent continues to require an explicit workspace. Bypass disables default reviews, preserves stricter worker policies and genuine questions, and provides no execution isolation. Use an externally isolated environment for unattended host execution.

Main-agent sessions retain their approval mode. Each new CLI launch restoring a bypass session requires the flag again, including launches that use /resume. Reviewed sessions must be resumed without it; start a new session to change modes. Existing compatible reviewed checkpoints retain their identities.

Headless main_agent never answers interrupts automatically. It saves questions and remaining tool reviews as waiting_for_user, prints the session ID, and exits with code 3. Exit code 0 means completion; 1 means execution, initialization, or output-export failure; 2 means invalid CLI/resume configuration. Ctrl+C returns 130 and closes the checkpoint runtime. --resume ID without a query reports the restored state. With -q, it starts a new turn only if that state is completed. If the session is waiting or failed, the query is skipped with a warning on stderr. Clarifications can use --answers-file as described below; other interrupts need interactive resume. Failed operations need interactive /retry. Completed tools are not replayed on restore. Recursion limits remain in effect; bypass does not add run-wide budgets or continuous goal execution.

Headless main_agent requires a CLI-restorable configuration. New runs using --mcp-url, --mcp-command, or their TOML equivalents are rejected before connecting to the server. Use interactive mode for MCP tools; those sessions do not support CLI restoration. A resumed session uses its saved configuration.

For headless main_agent, --output-file PATH writes UTF-8 assistant text with --output last_message (an empty file if no assistant text is available), or the graph state as JSON with --output state (the default). Session status and interrupt instructions stay in the terminal. The output directory must already exist. Serialization or write failures return 1, including when the session is waiting for input, without changing its saved status. Retry an export with --resume ID --output-file PATH without -q to avoid rerunning completed tools.

Machine-readable clarification handoff¶

Headless main_agent accepts --result-file PATH independently of --output and --output-file. Stdout remains human-readable. The UTF-8 JSON receipt has this shape (interrupt IDs come from the saved checkpoint):

{
  "version": 1,
  "session_id": "CHEMGRAPH_SESSION_ID",
  "status": "waiting_for_user",
  "assistant_response": "",
  "interrupts": [
    {"id": "INTERRUPT_ID", "kind": "clarification", "payload": {"question": "Which calculator?"}}
  ],
  "error": null,
  "error_code": null,
  "exit_code": 3
}

Before executing a new query or validated answers, ChemGraph atomically writes status: "running" with the session ID, empty response/interrupts, and null exit_code, error, and error_code. If that write fails, the graph does not run. The final receipt replaces it. Inspection-only invocations report the restored state without publishing a running receipt.

Final status is completed, waiting_for_user, or failed when known; otherwise it is null. session_id is null when no session was established. exit_code records the CLI outcome; error_code and human-readable error are null when no CLI error occurred. A completed session can still have an export error. Interrupt kinds are clarification, tool_review, and unsupported. An interrupt payload that cannot be encoded as strict UTF-8 JSON is replaced by a fixed message directing interactive inspection and marked unsupported; its ID and the waiting status/exit 3 are preserved.

`error_code`	Meaning
`invalid_answers`	Answer file is unreadable, malformed, or contains invalid values
`stale_answers`	Answer IDs do not exactly match all current pending IDs
`not_waiting`	The restored session is not waiting for input
`unsupported_interrupt`	File answers cannot handle the pending payload or missing IDs
`config`	Invalid CLI/configuration or incompatible resume
`execution`	Initialization, restoration, or execution failed
`export`	Output export failed; the saved session may already be completed
`interrupted`	KeyboardInterrupt was handled; exit 130

Receipt filesystem failures return 1 and print diagnostics; the destination may be unusable, so no new receipt or error code can be promised in that file. Existing exit codes are retained, including 1 for missing/malformed TOML.

To inspect without advancing the graph or calling the model/tools:

chemgraph run -w main_agent --dangerously-skip-approvals \
  --resume SESSION_ID --result-file /absolute/run/inspection-001.json

For clarification interrupts with stable IDs, write a JSON object mapping all current interrupt IDs to the user's nonempty answer strings, then resume:

{"INTERRUPT_ID": "Use EMT for this demonstration."}

chemgraph run -w main_agent --dangerously-skip-approvals --resume SESSION_ID \
  --answers-file /absolute/run/answers-001.json --result-file /absolute/run/result-002.json

Answers require --resume and cannot be combined with --query or --interactive. Malformed JSON, duplicate keys, empty answers, missing/extra/stale IDs, and sessions that are no longer waiting are rejected with exit 2 before executing the graph. Only the built-in {"question": "..."} payload is supported for file answers; tool reviews and other payloads require interactive resume. A continuation can ask again and exit 3, with new IDs in its receipt.

The result directory must already exist. Receipts are serialized before being atomically replaced; a write failure returns 1 without changing saved status. Each invocation requires a new result path: an existing destination is left untouched and returns 1 before graph execution. Answer, result, and output files must have distinct paths. Expected configuration and mode errors after argument parsing also write receipts when the destination is usable and does not alias the answer/output files. Argument-parser failures, invalid/colliding destinations, and termination before session creation may leave no receipt; consult the exit code and logs.

SIGTERM and abrupt crashes can leave the running receipt. Once the process has stopped, that receipt means the outcome is uncertain, not that work is still running. The early session ID does not guarantee that a checkpoint was saved. Reconcile the known process before inspecting or continuing; do not automatically replay uncertain operations. Stopping the CLI does not cancel external jobs. Serialize all operations on each session, including inspection; these flags provide no concurrent-writer coordination or session lock.

See the Hermes skill for relaying these questions and answers through Discord.

Saved sessions¶

CLI sessions are stored in ~/.chemgraph/sessions.db.

chemgraph session list
chemgraph session show <session-id>
chemgraph run --resume <session-id> -q "Continue with frequency analysis."

Run chemgraph session --help before deletion or other state-changing session operations. Resume a session with a compatible workflow.

Use MCP tools¶

Connect to one or more streamable-HTTP servers:

chemgraph run \
  --mcp-url http://localhost:9003/mcp/ \
  -q "Build a 3D structure for methane."

Use repeated/configured server definitions for larger deployments. See MCP servers for transports and client configuration.

Trace and dashboard¶

Use --trace-dir <directory> with single_agent to record trace information, then inspect the dashboard options available in your version:

chemgraph dashboard --help

Evaluation and Academy¶

Evaluation needs an explicit dataset or a configured profile:

chemgraph eval --help

Academy commands require the academy extra and, depending on the backend, additional execution extras:

chemgraph academy --help

See Evaluation and HPC and Academy.