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 |
-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 |
-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.
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.
Validate credentials¶
The check validates configuration; it does not prove that every external calculator, database, or facility endpoint is reachable.
Interactive mode¶
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. It requires interactive mode:
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.
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 unsafe flag is accepted only for non-interactive deep_agent, is not read
from TOML, and requires an explicit workspace. The backend's shell is not
confined to the workspace, so use a disposable, isolated environment.
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:
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:
Evaluation and Academy¶
Evaluation needs an explicit dataset or a configured profile:
Academy commands require the academy extra and, depending on the backend,
additional execution extras:
See Evaluation and HPC and Academy.