Skip to content
Back to Liquid Agent DOCUMENTATION

CLI Entrypoints

Npm User Entrypoint

Node owns the user-facing command-line entrypoint. Install local command shims from the repository checkout with:

./install_liquid_agent.command --user-data-dir "$HOME/Liquid Agent Data"

Equivalent terminal form:

./scripts/install_liquid_agent_cli.sh --user-data-dir "$HOME/Liquid Agent Data"

Primary commands:

  • liquid-agent
  • liq
  • liquid-agt
  • liquid-agent wiki
  • liquid-agent cli — explicit terminal mode
  • liquid-agent shell
  • liquid-agent portal
  • liquid-agent web
  • liquid-agent client
  • liquid-agent llm-status
  • liquid-agent llm-configure
  • liquid-agent update --check / liquid-agent update / liquid-agent update --rollback (macOS/Linux/Windows)
  • liquid-agent methods ...
  • liquid-agent results <dataset_folder>
  • liquid-agent skills ...
  • liquid-agent demo-check
  • liquid-agent assistant ...
  • liquid-agent assistant plan <dataset_folder>
  • liquid-agent assistant run <dataset_folder>
  • liquid-agent blood-agent ...

Aliases:

  • liquid-portal is equivalent to liquid-agent portal
  • liquid-web is equivalent to liquid-agent web
  • liquid-client is equivalent to liquid-agent client
  • liquidbiopsy-agent remains as a compatibility alias for older examples

The command invokes the Python analysis kernel internally. For conda installs, the installer captures the active non-base environment and later uses conda run, so users do not need to activate that environment first. Use LIQUID_AGENT_ENV=<env> to select another conda environment, or LIQUID_AGENT_PYTHON=/path/to/python for a direct Python kernel.

Python module/script commands below remain available for advanced and reproducible execution, but they are no longer the preferred interactive user interface.

The terminal shell starts with a compact ready panel by default. Set LIQUID_AGENT_STARTUP_VERBOSE=1 to print the full shell state and command help at startup.

Web UI

liquid-agent web
liquid-agent web --port 8771
liquid-agent web --no-open
liquid-web
liquid-agent portal
liquid-portal
liquid-agent client
liquid-agent client --port 8771
liquid-agent client --no-open
liquid-client

liquid-agent web and liquid-agent client both open the local Web workspace directly at /#/agent. Use liquid-agent wiki (also liquid-agt wiki or liq wiki) to open the separately deployed public homepage and Docs. In the interactive CLI, type wiki or /wiki; the CLI stays available. liquid-agent portal remains a compatible public-homepage entrypoint. Try it opens the installation documentation in the selected language; it does not run an analysis.

Use --no-open for a single launch that prints the URL without opening a browser automatically. Set LIQUID_AGENT_NO_OPEN=1 when you want that behavior for every browser launch in the current terminal session.

One-Shot Assistant

liquid-agent assistant plan /path/to/dataset
liquid-agent assistant run /path/to/dataset
liquid-agent assistant --input /path/to/dataset --print-only
liquid-agent assistant --input /path/to/dataset --execute

assistant plan is a user-friendly alias for planning without execution. assistant run plans and executes the recommended feasible task. The explicit --input form remains available for scripts and automation.

Metadata and Label Control

Inside the interactive shell:

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

The command reads the active dataset scan profile and reports the selected metadata table, sample id column, label column, label counts, coverage, confidence, supervision mode, and modeling backend. use overrides the automatic selection for the current session. ignore disables label-aware planning until metadata is rescanned or the session is reset.

The same metadata profile is attached to Web scan/plan responses and is summarized in the Web Metadata card.

Results

liquid-agent results /path/to/dataset
liquid-agent results /path/to/dataset --limit 100
liquid-agent results /path/to/dataset --json
liquid-agent results /path/to/dataset --ask 1 --question "What should I do next?"
liquid-agent results /path/to/dataset --ask 1 --llm-provider none

results lists generated Liquid Agent artifacts for a dataset, including reports, tables, JSON summaries, static figures, and ledger audit JSON such as analysis_concept_book.json. External HTML/site mirrors are filtered out so the list stays focused on agent-generated outputs. --ask <index> uses the same result-follow-up path as the interactive shell: it sends the selected artifact metadata and a safe excerpt to the configured LLM when available, then falls back to local artifact-context guidance if the LLM is disabled or unavailable. Ledger JSON artifacts such as plan records, run records, result evaluations, and concept books are summarized as plan state, task execution/verification, QC/findings/follow-ups, or pending/actioned/blocked result-driven memory instead of being shown as raw JSON. Autopilot Markdown reports are also summarized by stop reason, immediate next actions, completed workflow, result evaluation, and ledger status instead of returning only the raw excerpt. The local fallback also uses the artifact type to suggest the next safe action, for example continuing a recommended follow-up from a result evaluation, running a ready task from a plan, or fixing a recorded blocker before retrying a failed run. Plan-record follow-up summaries include the backend recommendation audit when present, so results --ask can explain whether minimum-output gaps, FeatureBook tie-breakers, or de-duplication changed the recommended task.

Professional Skills

Npm CLI:

liquid-agent skills list
liquid-agent skills show <skill_id>
liquid-agent skills context "methylation QC encoder selection"
liquid-agent skills ingest <path_or_url> --title "Methylation Cohort Interpretation Notes"
liquid-agent skills remember "If the assay family is unclear, inspect raw signal summaries before choosing an encoder."
liquid-agent skills remember --memory-type personal --note "Show figures before long tables in demos."
liquid-agent skills preference "Show figures before long tables in demos."
liquid-agent skills root

Inside the interactive shell:

/use <path> [path2 ...]
/sources
/sources add <path>
/sources remove <index|name|path>
/sources clear
/skills
/skills show <skill_id>
/skills ingest <path_or_url>
/skills remember <professional observation>
/skills preference <personal workflow preference>
/skills root
/skills refresh
/skills context <query>
/skills explain-plan

/use <parent_folder> can auto-detect multiple child liquid-biopsy datasets. /sources remove ... only detaches a source from the current task; it never deletes source files.

/autopilot writes closed-loop records under assistant/ledger/: plan_*.json, run_*.json, and result_evaluation_*.json. /skills explain-plan shows which machine-readable skill workflows affected the current plan.

liquid-agent skills ingest accepts local files, folders, URLs, and PDFs when the optional skills extra is installed. It uses the configured LLM for distillation when available and falls back to a local heuristic skill writer when no LLM is configured.

Personal preferences can be saved explicitly from the shell or naturally in chat:

/skills preference show plots first and keep the demo explanation concise.
Remember my preference: show plots first and keep the demo explanation concise.

Those notes are stored in user-workflow-preferences; expert or professional observations remain in professional-practice-notes.

The local web backend also exposes:

  • GET /api/session/{session_id}/sources
  • POST /api/session/{session_id}/sources
  • DELETE /api/session/{session_id}/sources/{selector}
  • DELETE /api/session/{session_id}/sources
  • GET /api/skills
  • GET /api/skills/{skill_id}
  • POST /api/skills/refresh
  • POST /api/session/{session_id}/skills/ingest
  • POST /api/session/{session_id}/skills/remember
  • GET /api/methods
  • POST /api/session/{session_id}/methods/advice

PDF ingestion requires the optional skills extra:

python -m pip install -e "[skills]"

Preprocessing

  • python scripts/preprocess_epigenomic_signal.py
  • python scripts/preprocess_lpwgs_signal.py
  • python scripts/preprocess_variant_signal.py

Blood Encoding

  • python scripts/encode_cfdna_foundation_features.py
  • python scripts/encode_epigenomic_signal_features.py
  • python scripts/encode_lpwgs_features.py
  • python scripts/encode_variant_features.py

cfDNA Downstream

  • python scripts/run_cfdna_plot_suite.py
  • python scripts/run_cfdna_analysis_suite.py
  • python scripts/run_cfdna_raw_signal_suite.py
  • python scripts/run_cfdna_raw_signal_analysis_suite.py

The standard cfDNA plotting CLI accepts --projection {auto,umap,tsne,pca} and defaults to auto.

Standard analysis and plotting can also consume processed supplied matrices:

python scripts/run_cfdna_analysis_suite.py \
  --cnv_matrix_table <cnv_matrix.tsv[.gz]> \
  --output_dir <analysis_output_dir>

python scripts/run_cfdna_plot_suite.py \
  --methylation_matrix_table <methylation_matrix.tsv[.gz]> \
  --output_dir <visualisation_output_dir>

Use --signal_matrix_table for other liquid-biopsy numeric matrices. Large tables are read responsively by default with --matrix_max_source_rows 50000; set it to 0 to read all rows.

Liquid-Biopsy Method Advisor

Interactive shell:

/methods fragmentomics CNV methylation
/methods check low-pass cfDNA WGS copy number
/methods run which tools should I use for cfMeDIP and fragmentomics?

Npm CLI:

liquid-agent methods --input <dataset_or_subdir> --query "fragmentomics CNV methylation"

Write report files:

liquid-agent methods \
  --input <dataset_or_subdir> \
  --query "fragmentomics CNV methylation" \
  --output-dir <output_dir>

Python script:

python scripts/run_liquid_biopsy_method_advisor.py \
  --input <dataset_or_subdir> \
  --query "fragmentomics CNV methylation" \
  --output_dir <output_dir>

The advisor checks assay-specific methods, local dependency availability, method-specific resources, and internal fallback routes. It can be called with only a natural-language query when no dataset is active.

Useful focused queries:

liquid-agent methods --query "cfDNAPro FinaleToolkit LBFextract fragmentomics"
liquid-agent methods --query "WisecondorX HMMcopy low-pass CNV"
liquid-agent methods --query "FinaleMe cfTools cfSort methylation tissue of origin"
liquid-agent methods --query "MethylBERT CelFEER UXM MethAtlas cfNOMe MetDecode methylation deconvolution"
liquid-agent methods --query "CpGPT MethylGPT MethFormer methylation foundation model"
liquid-agent methods --query "PureCN FACETS BayesCNV CopywriteR targeted ctDNA CNV"
liquid-agent methods --query "cfDNAFE cfDNAanalyzer EMIT DeepFRAG fragmentomics"

External Tool Runtime Manager

Use this layer when a recommended method has a registered non-kernel runtime and you want Liquid Agent to check, install, smoke-test, or call it through a stable wrapper.

Show all tools:

liquid-agent tools status

One-command setup:

liquid-agent tools bootstrap
liquid-agent tools bootstrap --execute
liquid-agent tools bootstrap --profile all --execute

Inspect one tool:

liquid-agent tools status --tool purecn
liquid-agent tools status --tool purecn --json

Install or prepare a runtime:

liquid-agent tools install purecn
liquid-agent tools install purecn --execute

Smoke-test a runtime:

liquid-agent tools smoke purecn
liquid-agent tools smoke facets
liquid-agent tools smoke dorado_modkit

Run a tool command through the wrapper:

liquid-agent tools run cnvkit -- cnvkit.py --help
liquid-agent tools run purecn -- Rscript -e "library(PureCN); packageVersion('PureCN')"
liquid-agent tools run dorado_modkit -- modkit --version

Run the internal CopywriteR-like compatibility proxy when the original legacy runtime is not suitable:

liquid-agent copywriter-proxy \
  --input <interval_or_bin_dir> \
  --output-dir <output_dir> \
  --exclude-regions <targets_or_peaks.bed>

This is a first-pass off-target/bin-count CNV screening route. It does not claim full equivalence to the original CopywriteR R/Bioconductor workflow.

Write tool status reports:

liquid-agent tools status --output-dir <output_dir>

installed=True means the runtime is callable. ready=True additionally means method-specific inputs, reference files, model checkpoints, and other real-analysis resources are configured. Legacy methods that cannot be installed cleanly, such as CopywriteR on macOS arm64, are marked as reimplementation candidates instead of being silently hidden.

Users should not manually activate external envs. Liquid Agent calls them internally through the wrapper layer.

Command Cookbook

For script-first examples, see the repository-level scripts/README.md command cookbook.

Default launch behaviour

liquid-agent, liquid-agt and liq without a subcommand open the local Web workspace. liquid-agent cli opens the terminal shell; shell remains a compatibility alias. wiki opens the public homepage and Docs. --help prints help without opening the browser.