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/helixlife/config.json, and finally defaults to opencode. --agent is kept as a compatibility alias.

login, status, and logout are the primary auth entrypoints. exchange redeems membership codes for the current profile. 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.

Membership Exchange

xt exchange YOUR_CODE
xt exchange YOUR_CODE --profile opencode --json

xt exchange <code> calls /agent/ticket/exchange with the current profile token and sends the exchange code as code. If an upstream API returns a membership-required 403 such as:

{
  "success": false,
  "code": 403000101,
  "message": "您的账号暂无使用权限，需要购买会员，购买链接: https://www.helixlife.cn/main/vip",
  "data": {
    "vip_buy_link": "https://www.helixlife.cn/main/vip"
  }
}

the CLI reports both paths: open the returned purchase link to buy membership, or run xt exchange <兑换码> to redeem membership in the CLI.

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 prepare km_plot_gene --profile opencode --json --cloudDataId tcga-chol-2
xt tool exec km_plot_gene --profile opencode --json --cloudFilter '胆管癌' --cloudIndex 0
xt tool exec km_plot_gene --profile opencode --json --cloudDataId tcga-chol-2
xt tool specific-search km_plot_gene genes TP53 --profile opencode --json --cloudDataId tcga-brca-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 the following 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 xt tool cloud to inspect candidates, then pass --cloudFilter <keyword>, --cloudIndex <n>, or --cloudDataId <id> to tool prepare / tool exec
• modules without returned input metadata can be submitted with --specific / --set; the CLI sends an empty args_data.info payload

args_specific defaults come from the dynamic schema returned by Xiantao. Use repeated --specific flags to override a whole key or a nested dotted path; array paths use numeric indexes.

xt tool prepare km_plot_gene --profile opencode --json --cloudDataId tcga-brca-2 --specific 'genes=TP53[ENSG00000141510.17]'
xt tool prepare group_plot_clin --profile opencode --json --cloudDataId tcga-brca-2 --specific 'genes=["TP53[ENSG00000141510.17]"]' --specific 'clin_list_1n.0.variable=(临床)Age'
xt tool prepare cox_analysis_cloud --profile opencode --json --cloudDataId tcga-brca-2 --specific 'surv_list_nn.0.variable=(临床)Gender' --specific 'surv_list_nn.0.attrs_list.0.attrs=["Female [50]","Male [49]"]'

For Search-style args_specific fields, use xt tool specific-search <tool> <argsKey> <query> --json to retrieve normalized choices before setting the final value. Pass the same input selectors that the tool needs, such as --cloudDataId, --cloudFilter, --cloudIndex, or --selected.

Cloud Data Flow

xt tool cloud is the read-only helper for XTCloud modules. It lists candidate cloud records and only supports --json. Actual preparation and submission still happen through xt tool prepare and xt tool exec.

xt tool inspect km_plot_gene --profile opencode --json
xt tool cloud km_plot_gene --profile opencode --json --filter '胆管癌'
xt tool prepare km_plot_gene --profile opencode --json --cloudDataId tcga-chol-2
xt tool exec km_plot_gene --profile opencode --json --cloudDataId tcga-chol-2

Typical cloud flow:

• run xt tool inspect <tool_id> --json first and confirm inputs.cloud_available=true
• run xt tool cloud <tool_id> --json [--filter <keyword>] to list candidates; use data.choices[*].index or data_id from the JSON output
• if the filter matches one record, tool prepare / tool exec can use --cloudFilter <keyword> directly
• if multiple records match, retry with --cloudIndex <n> or --cloudDataId <id>; --cloudIndex is 0-based
• if you already have the full record payload, pass --cloudRecordJson or --cloudRecordFile to tool prepare / tool exec

Useful cloud flags:

• xt tool cloud: --filter, --page, --all, --argsKey, --recordJson, --recordFile
• xt tool prepare / xt tool exec: --cloudFilter, --cloudIndex, --cloudDataId, --cloudKey, --cloudRecordJson, --cloudRecordFile

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 only supports --json and returns structured cloud candidates via data.choices
• tool specific-search only supports --json and returns normalized dynamic args_specific choices 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
• if a command returns code=PERMISSION_REQUIRED, use the returned purchase link or redeem a membership code with xt exchange <code> --profile <profile> --json; do not treat it as a local input-file problem
• if a command returns code=RATE_LIMITED, treat it as an upstream submit-capacity problem rather than changing local input files
• 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 exchange
• xt auth exchange
• xt tool login

Config

• xt config get agent_api
• xt config set agent_api https://agent.helixlife.cn
• xt config get base-url
• xt config set base-url https://agent.helixlife.cn
• xt config get login-url
• xt config set login-url https://agent.helixlife.cn/

History

• xt history list
• xt history view
• xt history download
• xt history save
• xt history rename
• xt history delete

Tool Run

• xt tool search
• xt tool inspect
• xt tool cloud
• xt tool specific-search
• 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 Xiantao tool commands that accept --toolProductUuid, the default value is c0b6febb-52dd-4525-970a-61bbe9e263ff. You can override it with --toolProductUuid, XIANTAO_TOOL_PRODUCT_UUID, or ~/.config/helixlife/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, and XIANTAO_LOGIN_URL=https://agent.helixlife.cn/ to override the resolved login page value. The same values can be stored with xt config set agent_api ... and xt config set login-url ...; base-url is kept as a compatibility alias for agent_api. Environment variables take precedence over ~/.config/helixlife/config.json. Login stores the access token at ~/.config/helixlife/user-access-token.txt. xt exchange <code> uses that token to redeem membership through /agent/ticket/exchange. Set DEBUG_MODE=1 to print HTTP request and response debug payloads to stderr.

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 specific-search <tool_id> <argsKey> <query> --json searches dynamic Search-style args_specific options and strips frontend highlight markup from returned choices. 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.

xt tool cloud <tool_id> fetches paginated cloud candidates and returns a machine-friendly payload when --json is used. data.choices contains the short selector list with 0-based index, data_id, and label; records contains the full records; columns, filter, selected_record, pages_fetched, and pagination metadata are included for callers that need the full context. Use --page to fetch one page, --all to merge every page, and --argsKey only when the module's cloud field cannot be auto-detected. xt tool cloud uses --recordJson / --recordFile for the current record seed, while xt tool prepare and xt tool exec use --cloudRecordJson / --cloudRecordFile for the final selected record.

--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. Tools that return no input metadata can still submit in mode=none with --set / --specific; the CLI sends an empty args_data.info object. 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. --cloudRecordJson / --cloudRecordFile cannot be combined with --cloudFilter / --cloudDataId / --cloudIndex, and cloud selection flags cannot be combined with --demo or --file. 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 view <fuid> lists the downloadable files for one history record. xt history download <fuid> --device pdf downloads an existing history artifact by fuid; when a record exposes multiple files, pass --device, --item, --label, or use an --output path with a target extension. xt history save <fuid> <uuid> <module_id> <name> saves a direct analysis result into history. 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