Command-Line Interface (CLI)

BioCortex provides a full-featured CLI for running analyses, interactive REPL sessions, knowledge-graph operations, MCP server management, and launching the web interface—all from the terminal.

Invoking the CLI

After installation, install the package in editable mode so the biocortex command is available:

cd /path/to/BioCortex_dev
pip install -e .
biocortex --help

Without installing, you can run the CLI as a module:

python -m biocortex.cli --help

Commands Overview

Command	Description
`biocortex cli`	Start the full-featured BioCortex REPL (recommended).
`biocortex run`	Execute a single task (one-shot, non-interactive).
`biocortex interactive`	Start a basic interactive session.
`biocortex status`	Show system status (models, KG, tools).
`biocortex web`	Launch the Gradio or Next.js web interface.
`biocortex import-biomni`	Import tools from a Biomni installation.
`biocortex kg`	Knowledge graph: search, stats, context, add, load-go, mermaid.
`biocortex encode`	Encode biological data into embeddings.
`biocortex bench`	Run BixBench evaluation.

biocortex cli

The primary entry point for interactive use. Launches the full REPL with:

ASCII art banner and system info panel
Ghost-text placeholder suggestions (Tab to fill)
Slash command autocompletion with descriptions
Persistent bottom status bar (model · strategy · cost · context %)
Session management (save / resume)
Plan review — inspect and approve the analysis plan before execution
Clarification dialog — prompts for missing context (e.g. species for scRNA-seq)
MCP server management — start/stop external tool servers on demand

Usage:

biocortex cli [options]

Options:

Option	Short	Description
`--model`	`-m`	Reasoning model name override.
`--strategy`	`-s`	Default strategy: `auto`, `react`, `dag_parallel`, `mcts`, `hypothesis`.
`--data`	`-d`	Data directory path made available to the agent.
`--biomni`	—	Path to a Biomni installation (tool bridge).
`--output`	`-o`	Output directory for reports and artifacts.
`--docker`	—	Use Docker sandbox for code execution.

Example:

biocortex cli -m deepseek-reasoner -d ./data/patient_cohort -o ./results

Slash Commands

All slash commands support Tab autocompletion with inline descriptions. Partial commands are auto-resolved (e.g. /mod → /model).

Core

Command	Description
`/help`	Show full command reference with shortcuts and examples.
`/exit`	Exit BioCortex CLI.
`/clear`	Clear the screen (asks for confirmation).
`/new`	Start a new session while keeping history.

Agent & Model

Command	Description
`/model`	Switch reasoning model (numbered interactive picker).
`/strategy`	Switch strategy: `react` / `dag_parallel` / `mcts` / `hypothesis` / `auto`. Tab-completes choices.
`/plan`	Toggle plan-review mode on/off (pause before execution to inspect and approve the plan).
`/verbose`	Set verbose display mode (show all tool calls and intermediate output).
`/compact`	Set compact display mode (summaries only).
`/keys`	Configure API keys at runtime without restarting.

Data & Files

Command	Description
`/data [path]`	Set or display the data directory for this session.
`/qc [file]`	Quick QC summary of a data file (`.h5ad`, `.csv`, `.vcf`, etc.).
`/browse [dir]`	Browse output or data directory as a file tree.
`/formats`	Show all supported input/output file formats.

Analysis Shortcuts

Command	Description
`/case-study list`	List curated analysis templates (PBMC, mouse brain, spatial, etc.).
`/case-study <name>`	Preview and launch a curated template.
`/agents <n>`	Run the current task across N agent instances in parallel and compare results.

Session Management

Command	Description
`/sessions`	List saved sessions with IDs, dates, and task counts.
`/resume [id]`	Resume a saved session by ID, short prefix, or index (`last`).
`/compress`	Compress session context and display token savings.
`/diff [id1] [id2]`	Compare two session reports side-by-side.

Information & Diagnostics

Command	Description
`/tools [domain]`	List available tools by domain.
`/skills`	List available workflow skill templates.
`/config`	Show active runtime configuration.
`/status`	Detailed agent and system status.
`/doctor`	Run readiness diagnostics (API keys, databases, tool health).
`/usage`	Show session token count and cost summary.
`/tokens`	Detailed per-task token breakdown.
`/kg [search term]`	Knowledge graph stats; optionally search entities.

MCP Servers

Command	Description
`/mcp`	List all configured MCP servers and their status.
`/mcp start <name>`	Start a configured MCP server.
`/mcp stop <name>`	Stop a running MCP server.
`/mcp restart <name>`	Restart an MCP server.
`/mcp add <name> <cmd>`	Register a new STDIO MCP server (persisted to `.biocortex/mcp.json`).
`/mcp add <name> --uri <url>`	Register an HTTP MCP server.
`/mcp remove <name>`	Remove an MCP server configuration.
`/mcp tools`	List all tools currently exposed by running MCP servers.

Add options: --autostart (start on every launch), --desc 'description', --env KEY=VALUE

# Examples
/mcp add biomcp 'uv run --with biomcp-python biomcp run' --autostart
/mcp add ctx7 'npx -y @upstash/context7-mcp' --desc 'Library docs'
/mcp add remote --uri http://localhost:3000/mcp
/mcp tools

Export

Command	Description
`/export [path]`	Export last report to a Markdown file.
`/notebook [path]`	Export session as a Jupyter notebook (`.ipynb`).
`/cite`	Generate a Methods-section citation for tools used in this session.

Shell Passthrough

Prefix any shell command with ! to run it directly:

❯ !ls data/
❯ !python preprocess.py --input pbmc.h5ad
❯ !pip install scanpy

Multi-line Input

Press Ctrl+J or Alt+Enter to add a new line in the prompt (useful for multi-step instructions). Press Enter on an empty line to submit.

Keyboard Shortcuts

Key	Action
`Tab`	Fill ghost-text suggestion / complete slash command.
`Ctrl+J` / `Alt+Enter`	Insert newline (multi-line mode).
`Ctrl+O`	Toggle verbose/compact display mode.
`Ctrl+C`	Cancel current input line.
`Escape`	Cancel a running analysis task.
`↑ / ↓`	Navigate command history.

Analysis Display

When a task is running, the CLI shows a live panel:

📌 Analyzing PBMC single-cell RNA-seq data • 14s • [Esc] cancel
─────────────────────────────────────────────────────────
  Strategy: dag_parallel  |  Complexity: 0.7  |  Steps: 6
  ✓ load_and_qc_data           (4.2s)
  ✓ normalize_and_select_hvgs  (2.8s)
  • cluster_cells               running…
  ○ annotate_cell_types         pending
  ○ find_differentially_expressed_genes  pending
  ○ generate_report             pending
─────────────────────────────────────────────────────────
◎ deepseek-reasoner | agent: BioCortex | ctx: 3% | cost: $0.0124

For inquiry / chat mode (simple questions), the CLI shows a brief status line and outputs the answer directly — no full panel. Plan review (when enabled via /plan or config):

◎ Research Plan — Ready for Review
  1. Load .h5ad and run QC metrics
  2. Normalize, log-transform, select HVGs
  3. PCA + UMAP dimensionality reduction
  4. Leiden clustering (resolution 0.5)
  5. Cell-type annotation via CellTypist
  6. Differential expression (Wilcoxon)

  [1] Approve   [2] Continue Planning with feedback   [c] Cancel
Choice (1 / 2 / c):

Clarification Dialog

When you provide a data file without specifying key parameters (e.g. species for scRNA-seq), the CLI asks clarifying questions before starting analysis:

◎ Before we begin — a few quick questions

  1. Which species is this data from?
     [1] Human (Homo sapiens)
     [2] Mouse (Mus musculus)
     [3] Other (I'll specify)

  2. What tissue or cell type?
     [1] PBMC / immune cells
     [2] Brain / neural
     [3] Other

  Enter choice [1–3, c=cancel]:

Answers are injected into the task description before analysis starts, reducing annotation errors.

biocortex run

Execute a single task described in natural language. Output is written to a report file in the given output directory. Usage:

biocortex run "Task description"
biocortex run [options] "Task description"

Options:

Option	Short	Description
`--model`	`-m`	Reasoning model name (overrides config).
`--coder`	—	Code-generation model name.
`--strategy`	`-s`	Strategy: `react`, `dag_parallel`, `mcts`, or `hypothesis`.
`--biomni`	—	Path to Biomni installation (tool bridge).
`--data`	`-d`	Data directory path.
`--output`	`-o`	Output directory (default: `./output`).
`--docker`	—	Use Docker sandbox for execution.
`--timeout`	—	Execution timeout in seconds (default: 600).

Examples:

biocortex run "Analyze BRCA1 expression in TCGA breast cancer data"
biocortex run -m gpt-4o -s dag_parallel -o ./my_out "Design CRISPR sgRNAs targeting BRCA1"
biocortex run -d ./data --docker "Run Scanpy QC on pbmc.h5ad"

biocortex interactive

Start a simplified interactive session. For the full-featured REPL (slash commands, session management, MCP, etc.), use biocortex cli instead. Usage:

biocortex interactive [--model MODEL] [--biomni PATH]

In-session commands:

Command	Description
`<task>`	Run a biological analysis task.
`status`	Show agent status (models, tools, memory, KG).
`clear`	Clear working memory.
`kg <query>`	Search the knowledge graph.
`help`	List available commands.
`exit` / `quit` / `q`	Quit the session.

biocortex status

Print system status without loading heavy models. Shows configured reasoning/coder/fast models, strategy, Docker setting, timeouts, data/output paths, knowledge-graph stats, and multimodal/embedding status. Usage:

biocortex status

biocortex web

Launch the web interface (Gradio or Next.js). Usage:

biocortex web [options]

Options:

Option	Short	Description
`--port`	`-p`	Server port (default: 7860).
`--frontend`	—	`gradio` (legacy) or `next` (React).
`--model`	`-m`	Reasoning model override.
`--biomni`	—	Path to Biomni.
`--use-auth`	—	Enable login authentication.
`--auth-users`	—	Comma-separated `username:password` pairs.
`--allow-register`	—	Allow new user registration.
`--admin-user`	—	Username treated as admin (default: `admin`).
`--share`	—	Create a public Gradio link (Gradio frontend only).

Examples:

biocortex web -p 7860 --frontend next
biocortex web -p 7860 --frontend next --use-auth --auth-users "admin:pass1" --allow-register

biocortex import-biomni

Import tool descriptions and functions from a local Biomni installation into BioCortex’s registry. Usage:

biocortex import-biomni /path/to/Biomni/biomni

biocortex kg

Knowledge-graph operations. Use a subcommand after kg.

kg search

biocortex kg search BRCA1
biocortex kg search "cell type" --type gene --limit 20

kg stats

biocortex kg stats

kg context

biocortex kg context BRCA1 --depth 2 --triples 20

kg add

biocortex kg add "BRCA1" "associated_with" "breast cancer" --source cli

kg load-go

biocortex kg load-go /path/to/go-basic.obo

kg mermaid

biocortex kg mermaid

biocortex encode

Encode biological data (protein/DNA/RNA sequence, structure, or image) into vector embeddings. Usage:

biocortex encode <modality> <data> [--id ID] [--save PATH]

Modalities: protein, dna, rna, structure, image Examples:

biocortex encode protein "MKWVTFISLLLLFSSAYS" --id BRCA1
biocortex encode protein "MKWVTFISLLLLFSSAYS" --id BRCA1 --save ./brca1_emb.npy

biocortex bench

Run evaluation using a BixBench-style manifest. Usage:

biocortex bench [options]

Common options:

Option	Short	Description
`--manifest`	`-m`	Path to manifest JSON (default: `./bixbench/manifest.json`).
`--output`	`-o`	Output directory (default: `./bench_results`).
`--parallel`	`-p`	Parallel question threads (default: 4).
`--timeout`	—	Per-question timeout in seconds (default: 300).
`--max-steps`	—	Max agent steps per question (default: 15).
`--model`	—	Override reasoning model.
`--strategy`	`-s`	`auto`, `react`, `dag_parallel`, `mcts`, or `hypothesis`.
`--question`	—	Run a single question by ID.
`--max-questions`	`-n`	Limit to first N questions.
`--dry-run`	—	Preview questions without running.
`--no-eval`	—	Skip LLM-as-judge scoring.
`--only-failed`	—	Re-run only previously failed questions.

MCP — Model Context Protocol

BioCortex supports the Model Context Protocol (MCP) for extending the agent’s tool set with external services. All MCP servers are aggregated behind a single HTTP gateway (http://127.0.0.1:3100/mcp) and their tools are automatically injected into the agent’s context.

How It Works

mcp.json  (config)
    ↓
MCPManager  (lifecycle: start / stop / prewarm)
    ↓
UnifiedMCPGateway  (port 3100)
    ├── biomcp_search_genes
    ├── biomcp_search_variants
    ├── context7_resolve_library_id
    └── …
    ↓
MCPProvider  (TTL-cached tool list + call_tool)
    ↓
BioCortex Agent  (tools injected into LLM prompt)

Configuration File

Create .biocortex/mcp.json in your project directory (or ~/.biocortex/mcp.json for global config):

{
  "host": "127.0.0.1",
  "port": 3100,
  "cache_ttl": 60,
  "auto_start": ["biomcp"],
  "servers": {
    "biomcp": {
      "type": "stdio",
      "command": "uv run --with biomcp-python biomcp run",
      "description": "Gene/variant/trial search (NCBI, ClinVar, ClinicalTrials.gov)"
    },
    "context7": {
      "type": "stdio",
      "command": "npx -y @upstash/context7-mcp",
      "description": "Up-to-date library and API documentation"
    },
    "my_remote": {
      "type": "http",
      "uri": "https://my-mcp-server.example.com/mcp",
      "description": "Custom remote MCP service"
    }
  }
}

Config priority (highest → lowest): ~/.biocortex/mcp.json → .biocortex/mcp.json → package defaults.

Server Types

Type	Description
`stdio`	Local subprocess managed by BioCortex. BioCortex starts, monitors, and stops the process. Per-server logs written to `~/.biocortex/logs/mcp/`.
`http`	Remote HTTP MCP endpoint already running. BioCortex connects and proxies tools.

Pre-configured Servers

Name	Command	Tools Available
`biomcp`	`uv run --with biomcp-python biomcp run`	Gene search, variant lookup, clinical trial search via NCBI/ClinVar
`context7`	`npx -y @upstash/context7-mcp`	Library documentation, API reference lookup
`filesystem`	`npx -y @modelcontextprotocol/server-filesystem .`	Local file read/write
`pubmed`	`uvx mcp-server-pubmed`	PubMed literature search

All are disabled by default — add names to auto_start or use /mcp start <name> to enable.

Installing MCP dependency

pip install fastmcp

Configuration and Environment

CLI commands use the same configuration as the rest of BioCortex. Set environment variables in the project root .env or in ~/.biocortex/.env:

OPENAI_API_KEY=sk-...
REASONING_MODEL=deepseek-reasoner
CODER_MODEL=deepseek-chat
FAST_MODEL=deepseek-chat

# Optional: web search keys for native search tools
TAVILY_API_KEY=tvly-...
SERPER_API_KEY=...
NCBI_EMAIL=you@example.com

Next Steps

Getting Started — Install and run your first analysis.
Strategy Routing — How tasks are classified and routed.
Web UI — Use the browser instead of the CLI.
Configuration — Full list of options and environment variables.
MCP Integration — Detailed MCP server setup and authoring.

Getting Started

Core Framework

Tools & Extensions

Web & Automation

Deployment & auth

Advanced

Reference

​Command-Line Interface (CLI)

​Invoking the CLI

​Commands Overview

​biocortex cli

​Slash Commands

​Core

​Agent & Model

​Data & Files

​Analysis Shortcuts

​Session Management

​Information & Diagnostics

​MCP Servers

​Export

​Shell Passthrough

​Multi-line Input

​Keyboard Shortcuts

​Analysis Display

​Clarification Dialog

​biocortex run

​biocortex interactive

​biocortex status

​biocortex web

​biocortex import-biomni

​biocortex kg

​kg search

​kg stats

​kg context

​kg add

​kg load-go

​kg mermaid

​biocortex encode

​biocortex bench

​MCP — Model Context Protocol

​How It Works

​Configuration File

​Server Types

​Pre-configured Servers

​Installing MCP dependency

​Configuration and Environment

​Next Steps

Command-Line Interface (CLI)

Invoking the CLI

Commands Overview

biocortex cli

Slash Commands

Core

Agent & Model

Data & Files

Analysis Shortcuts

Session Management

Information & Diagnostics

MCP Servers

Export

Shell Passthrough

Multi-line Input

Keyboard Shortcuts

Analysis Display

Clarification Dialog

biocortex run

biocortex interactive

biocortex status

biocortex web

biocortex import-biomni

biocortex kg

kg search

kg stats

kg context

kg add

kg load-go

kg mermaid

biocortex encode

biocortex bench

MCP — Model Context Protocol

How It Works

Configuration File

Server Types

Pre-configured Servers

Installing MCP dependency

Configuration and Environment

Next Steps