npm package: @helixlife-ai/xiantao
Description: CLI for Xiantao bioinformatics tools
Author: helixlife-ai
Latest version: 0.1.22

# 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

```bash
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

```bash
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

```bash
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`](/Users/chenyunjie/Desktop/xtz-cli/xiantao/docs/GSEA-基因集.csv) and [`docs/GSEA-分子.xlsx`](/Users/chenyunjie/Desktop/xtz-cli/xiantao/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

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

## Publish

```bash
npm publish
```

## Autocomplete

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

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

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

Install shell completion locally with:

```bash
xt autocomplete zsh
xt autocomplete bash
xt autocomplete powershell
```