Back to Liquid Agent DOCUMENTATION

Interactive Shell

Start the shell with:

liquid-agent cli

The shell supports assistant, blood, and chat modes. It can bind a dataset path from natural language, scan files, produce a readable plan, execute tasks, recover from safe failures, and summarize outputs.

The shell is a terminal presentation layer over the same LangGraph interaction and analysis runtime used by the Web client. Free-form instructions are sent to the shared intent router rather than being reduced to a fixed terminal command table. Exact slash commands remain deterministic escape hatches.

Type wiki (or /wiki) at the CLI prompt to open the public project homepage and Docs in your browser. The CLI stays available. From a terminal, use liquid-agent wiki, liquid-agt wiki, or liq wiki.

First Prompt

I want to use this dataset folder: <dataset_or_subdir>

<dataset_or_subdir> may be an absolute path or a dataset name relative to the configured data root. The assistant will scan the folder and return a planning brief. If you accept the plan or give a firm instruction, it can run the feasible workflow end to end.

If the selected folder contains multiple actionable liquid-biopsy datasets, the shell automatically treats them as separate sources for one joint task. You can also start joint analysis explicitly:

/use <dataset_a> <dataset_b>

Manage the current source list without touching files on disk:

/sources
/sources add <dataset_c>
/sources remove <index|name|path>
/sources clear

In multi-source mode, the assistant plans source-specific preprocessing and analysis first, then writes a joint source inventory and report under assistant/joint_reports/.

Common Requests

Run the full analysis end to end.

Focus on cfDNA analysis first.

Inspect the raw signal before encoding.

Encode this blood-biopsy batch with the most stable default encoder.

Plot the encoded cfDNA samples and colour by the metadata column closest to HER2.

Use the metadata table if it has reliable labels; otherwise keep the plan unsupervised.

Explain what the last result means and where the outputs are stored.

What encoder models do you support?

What mature tools should I consider for fragmentomics, methylation, and CNV in this dataset?

Capability and support questions are checked against structured project facts. If the LLM gives a thin or incomplete answer, the shell repairs it or falls back to a deterministic answer with concrete function blocks, scripts, encoders, or docs paths.

Primary Commands

/use <path>
/sources
/mode <assistant|blood|chat>
/plan
/autopilot
/run
/review
/methods
/metadata
/llm
/skills
/output
/help

/autopilot runs the closed-loop assistant kernel: it writes versioned assistant/ledger/plan_*.json, run_*.json, and result_evaluation_*.json records as it works, then writes an audit-style Markdown report under assistant/reports/. The compiled analysis graph checkpoints conversation state separately from those scientific audit files, so an interrupted run can reuse completed work without treating a partial task as complete.

Method advice commands:

/methods fragmentomics CNV methylation
/methods check low-pass cfDNA WGS copy number
/methods run which tools should I use for cfMeDIP and fragmentomics?
/methods cfDNAPro FinaleToolkit LBFextract fragmentomics
/methods WisecondorX HMMcopy low-pass CNV
/methods FinaleMe cfTools cfSort methylation tissue of origin
/methods MethylBERT CelFEER UXM MethAtlas cfNOMe MetDecode methylation deconvolution
/methods CpGPT MethylGPT MethFormer methylation foundation model
/methods PureCN FACETS BayesCNV CopywriteR targeted ctDNA CNV
/methods cfDNAFE cfDNAanalyzer EMIT DeepFRAG fragmentomics

/methods run writes JSON and Markdown advice reports under the analysis output root. The same route is available through natural language when the user asks for tools, algorithms, mature assay-specific methods, or research/watchlist methods.

External runtime commands:

/tools
/tools status purecn
/tools bootstrap
/tools bootstrap --execute
/tools install purecn
/tools install purecn --execute
/tools smoke purecn
/tools run cnvkit -- cnvkit.py --help

/tools bootstrap and /tools install are dry runs unless --execute is present. installed=True means the runtime is callable. ready=True additionally means real input files, reference resources, model checkpoints, or panel resources are configured. Users do not manually activate isolated envs; the shell calls them through Liquid Agent wrappers.

For BED-style cohort folders, autopilot accepts plain .bed and .bed.gz files. If a user metadata table such as metadata.csv contains sample_id and a label/status column, the assistant can use it for grouped summaries and coloured visualisations. If sequence encoding needs a FASTA that has not been set, the run records that blocker and keeps going with downstream statistics and raw-signal tasks that do not need the FASTA.

Metadata commands:

/metadata
/metadata use <table> <sample_col> <label_col>
/metadata ignore
/metadata rescan

/metadata shows detected metadata tables, selected label, class counts, coverage, planning mode, and backend. /metadata use ... manually overrides the selection. /metadata ignore rebuilds the next plan as unsupervised for the current session.

LLM Control

OpenAI GPT is the default online backend; Gemini 3.8 Flash is an optional backend. One OpenAI API key works across the model tiers.

/llm models
/llm key
/llm use auto
/llm save

To use a more capable, higher-cost model, use /llm use gpt-6-sol or /llm use gpt-6-astra, then /llm save to persist the choice. /llm delete openai deletes the saved key and disables environment fallback. /llm off is an explicit offline diagnostic mode, not an alternative provider. Switching GPT models refreshes project docs and skill context. OpenAI failures produce an error rather than switching providers or silently selecting a more expensive model. See OpenAI configuration.

For optional Gemini use, run /llm key gemini, /llm use gemini, then /llm save. Use public or non-sensitive synthetic data and check Google's free-tier eligibility and regional terms first; see Gemini configuration.

Skills

/skills list
/skills ingest <path_or_url>
/skills remember <professional observation>
/skills preference <personal workflow preference>
/skills refresh
/skills context <query>
/skills explain-plan

Use skills for durable professional knowledge, paper-derived notes, expert workflow observations, personal display/workflow preferences, and checking which professional context is available for a topic.

/skills explain-plan shows which machine-readable skill workflows influenced the active plan, including required outputs and quality checks.

Exit Behavior

Slash commands work:

/quit
/exit

Plain-language leave intents also work:

bye bye
quit
exit
see you later

Ambiguous leave intents are confirmed before the shell exits.

Linking tasks and memory

Use /conversations to list task IDs, /link <id> <id> [...] to begin a synthesis conversation, and /memory to inspect the current memory and its location. See Linked Tasks and Local Memory.