xt

CLI for Xiantao bioinformatics tools.

Install with npm i -g @helixlife-ai/xiantao and run it as xt.

tool is the primary product topic for bioinformatics tools. plot is kept as a compatibility entrypoint for the current command set and prints a migration warning when executed.

--profile is the primary profile selector for token lookup and config isolation. If it is omitted, the CLI resolves the profile from AGENT_NAME, then the host runtime (cursor, opencode, openclaw), then ~/.config/xtz/config.json, and finally defaults to opencode. --agent is kept as a compatibility alias.

login, status, and logout are the primary auth entrypoints. auth ... is kept as a compatibility topic and prints a migration warning when executed.

Main Flows

First Use

xt login
xt tool search violin
xt tool inspect violin_flat
xt tool run violin_flat ./data.xlsx

xt login is the recommended first-use entrypoint. It authorizes and stores the profile token in one step. xt tool login is kept as an equivalent entrypoint under the tool topic.

Interactive Tool Run

xt tool run --interactive

This starts a menu-driven path for choosing a tool, selecting demo data or a local file, filling dynamic args_main, and optionally downloading generated outputs.

Agent Automation

xt tool prepare violin_flat --file ./data.xlsx --profile opencode --json
xt tool exec violin_flat --file ./data.xlsx --profile opencode --json
xt tool exec violin_flat --file ./data.xlsx --profile opencode --json --download ./violin.pdf

xt tool exec gsea_analysis --demo --profile opencode --json
xt tool prepare gsea_plot --profile opencode --json
xt tool exec gsea_plot --profile opencode --json --download ./gsea_plot.pdf
xt tool exec gsea_customize --file gene_set=./gene_set.gmt --file data=./rank.xlsx --profile opencode --json

xt tool cloud km_plot_gene --profile opencode --json --filter '胆管癌'
xt tool exec km_plot_gene --profile opencode --json --cloudFilter '胆管癌'
xt tool exec km_plot_gene --profile opencode --json --cloudFilter '胆管癌' --cloudIndex 1
xt tool exec km_plot_gene --profile opencode --json --cloudDataId tcga-chol-2

For machine callers, use xt tool prepare to fetch the final schema, then xt tool exec to submit. Keep --json, pass an explicit profile with --profile, and avoid interactive-only flows. The examples below illustrate command shapes, not a fixed allowlist of tools. Apply the same patterns to any tool with the same input mode.

xt tool prepare and xt tool exec support three input patterns:

• upload modules: pass --file <xlsx>
• multi-upload modules: repeat --file key=path, for example --file gene_set=./gene_set.gmt --file data=./rank.xlsx
• demo-capable upload modules: pass --demo
• history-record modules such as gsea_plot: pass neither --file nor --demo; the CLI reuses the default XTRecord returned by tool inspect / tool prepare
• cloud-capable modules: use --cloudFilter <keyword> to narrow cloud records, then retry with --cloudIndex <n> or --cloudDataId <id> when multiple matches exist

Current operational notes for agent-style callers:

• serialize xt tool exec submits per profile; Xiantao may reject overlapping or too-frequent submits with NETWORK_ERROR
• tool inspect now includes the full args_data payload in JSON output and summarizes every detected XTUpload field
• tool inspect also reports inputs.cloud_available and inputs.cloud_default for XTCloud modules
• for multi-upload modules, pass keyed uploads in the same field names returned by tool inspect
• tool cloud --json --filter <keyword> returns structured cloud candidates via data.choices
• if tool prepare or tool exec returns code=TOOL_AMBIGUOUS with data.selection_type=cloud_record, do not auto-pick; ask the user which item to use, then retry with --cloudIndex or --cloudDataId
• gsea_customize has been validated through tool prepare and tool exec with repeated --file gene_set=... --file data=...

For agent workflows, do not use xt tool run. Treat xt tool run as the human-first path and xt tool exec as the machine path.

xt login --json now returns the authorization link immediately and defaults to authorized: false until the browser step completes. Use xt login --json --wait when you explicitly want the command to block until authorization is confirmed. xt status is a probe-style check and returns authorized: true or authorized: false together with a reason such as missing_token or expired_token.

Command Groups

Auth

• xt login
• xt status
• xt logout
• xt tool login

History

• xt history list
• xt history download
• xt history rename
• xt history delete

Tool Run

• xt tool search
• xt tool inspect
• xt tool cloud
• xt tool prepare
• xt tool run
• xt tool exec
• xt tool download

Tool Debug

• xt tool resolve
• xt tool menu
• xt tool menus
• xt tool menus-raw
• xt tool fetch-all

Notes

For the common Xiantao tool product, tool search, tool inspect, tool run, tool resolve, and tool menu default toolProductUuid to c0b6febb-52dd-4525-970a-61bbe9e263ff. You can override it with --toolProductUuid, XIANTAO_TOOL_PRODUCT_UUID, or ~/.config/xtz/config.json under xiantao.toolProductUuid.

The CLI also loads a project-root .env file on startup. You can set XIANTAO_BASE_URL=https://agent.helixlife.cn there to switch the API base URL without prefixing each command manually.

xt tool search <keyword> searches remote tool menus by tool id, title, path, and route. xt tool inspect <tool_id> prints resolved metadata together with the dynamic args_main schema, the full args_data payload in JSON mode, and the detected input source summary, including XTCloud, per-field XTUpload, and XTRecord defaults. xt tool cloud <tool_id> fetches paginated cloud candidates and returns a machine-friendly data.choices list when --json is used. xt tool run <tool_id> runs a Xiantao bioinformatics tool in the human-first path. xt tool exec <tool_id> is the agent-safe submit command and also supports --download <path> when a local artifact is needed. xt tool resolve <tool_id> remains available as the low-level UUID and route lookup. xt tool menus returns a concise catalog with each tool title, module_id, path, and route, which is useful when tool search finds nothing helpful or when you want to shortlist tools for recommendation. --demo reuses the demo file metadata returned by tool fetch-all; --file uploads a local file first; multi-upload modules accept repeated --file key=path; for XTRecord modules the CLI can submit directly from the default history record returned by fetch-all; for XTCloud modules use --cloudFilter, then --cloudIndex or --cloudDataId to pin one cloud record before submit. Run xt login first to authorize the stored token. When cloud filtering matches multiple records, tool prepare and tool exec return code=TOOL_AMBIGUOUS plus data.selection_type=cloud_record and data.choices; callers should ask the user which record to use before retrying. When a tool exposes multiple downloadable results, --download <path> uses the output file extension to select the matching artifact.

For the current GSEA tool family, gsea_plot, gsea_plot2, gsea_bar, gsea_point, gsea_ridge, gsea_emapplot, gsea_tree, and gsea_path_cluster are record-backed visual modules that reuse the default gsea_analysis history record. gsea_analysis itself is an upload/demo analysis module. gsea_customize is a custom gene-set upload module whose frontend expects two uploads, gene_set and data; submit it with --file gene_set=... --file data=.... A real CLI submit path has been verified with the sample files in docs/GSEA-基因集.csv and docs/GSEA-分子.xlsx.

xt tool run <tool_id> ... --interactive prompts for dynamic args_main values before the final submit, prints reusable --set flags, and supports < for the previous item plus /skip for the current section.

xt history list lists the current profile's history records and shows the latest fuid, status, module, and time for each record. xt history download <fuid> --device pdf downloads an existing history artifact by fuid; when a record exposes multiple files, pass --device or use an --output path with a target extension. xt history rename <fuid> <name> renames a record, and xt history delete <fuid> deletes it.

Development

npm install
npm run build
node ./bin/run.js --help

Publish

npm publish

Autocomplete

oclif supports shell completion through @oclif/plugin-autocomplete.

Refresh the checked-in completion files in this repo with:

XT_CACHE_DIR=$PWD/.xtz-cache node ./bin/run.js autocomplete --refresh-cache

Install shell completion locally with:

xt autocomplete zsh
xt autocomplete bash
xt autocomplete powershell