{ "name": "@qoder-ai/qmind-cli", "version": "4.1.0", "description": "QMind command line interface", "bin": { "qmind": "bin/cli.js" }, "type": "module", "sideEffects": false, "files": [ "bin", "dist", "CHANGELOG.md", "CHANGELOG.zh-CN.md", "README.md", "README.zh-CN.md" ], "engines": { "node": ">=22.19.0" }, "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org" }, "dependencies": { "commander": "15.0.0", "entities": "8.1.0", "eventsource-parser": "4.1.2", "open": "11.0.4", "p-limit": "7.3.3", "picomatch": "4.0.7", "proper-lockfile": "4.1.2", "semver": "7.8.5", "undici": "8.12.2", "zod": "4.6.7" }, "devDependencies": { "@types/node": "24.13.3", "@types/picomatch": "4.0.3", "@types/proper-lockfile": "4.1.4", "@types/semver": "7.8.0", "@ali/qmind-agent-core": "^5.4.0", "@ali/qmind-node-host": "^3.0.2", "@ali/qmind-sdk": "^0.35.0" }, "license": "UNLICENSED", "readme": "# QMind CLI for Qoder Global\n\n[简体中文](./README.zh-CN.md)\n\nThe QMind command-line interface for Qoder Global lets you sign in, manage knowledge bases and sources, retrieve content, run RAG and task workflows, and synchronize local directories.\n\nPackage: `@qoder-ai/qmind-cli` · command: `qmind`\n\n## Install\n\nNode.js `>=22.19.0` is required.\n\n```sh\nnpm install --global @qoder-ai/qmind-cli\nqmind version\nqmind --help\n```\n\nUpgrade and uninstall through npm. `qmind self-update` only prints the npm upgrade command and never modifies npm-managed files.\n\n```sh\nnpm update --global @qoder-ai/qmind-cli\nnpm uninstall --global @qoder-ai/qmind-cli\n```\n\nThe Native standalone CLI uses the verified Global release channel instead. An installer-managed\nNative executable can check or apply the latest release without Node.js or npm:\n\n```sh\nqmind update --check\nqmind update\n```\n\n`self-update` remains an alias for `update`. The updater rejects channel/URL overrides, downgrades,\nunowned executables, release checksum mismatches, and modified installer bytes. Windows schedules\nreplacement after the running executable exits and records details beside the executable.\n\n## Quick start\n\n```sh\nqmind login\nqmind notebook list\nqmind source list --nb \nqmind retrieve --nb \"What must be checked before release?\"\n```\n\nInteractive login opens a browser and stores the session in a local file vault. For CI and agents, prefer an environment variable and structured output:\n\n```sh\nexport QMIND_TOKEN=''\nqmind notebook list --non-interactive --format json\nqmind retrieve --nb --format agent \"What is the deployment process?\"\n```\n\nDo not put tokens in command arguments, repositories, or logs. Run `qmind logout` to remove the current local session.\n\n## Commands\n\n| Command | Purpose |\n| ------------------------ | ---------------------------------------- |\n| `login` / `logout` | Sign in or remove local credentials |\n| `notebook` | Manage knowledge bases |\n| `source` | Manage knowledge-base sources |\n| `retrieve` | Retrieve context without invoking an LLM |\n| `rag` | Ask questions using a knowledge base |\n| `task` | Manage task runs |\n| `scheduled-task` | Manage notebook schedule configurations |\n| `upload-folder` / `sync` | Synchronize a local directory |\n| `image` | Obtain image upload or access URLs |\n| `version` | Print version and build information |\n| `update` / `self-update` | Update an installer-managed Native CLI |\n\n`task create` does not start `compilation` or `lint` runs; `task list` and `task get` can still inspect historical runs for those scenes. `source import-site` does not provide an automatic compilation option.\n\nRun `qmind --help` for complete options. Domain commands support formats such as `table`, `json`, `agent`, and `ndjson`. stdout contains results; progress and diagnostics go to stderr. Exit codes are `0` for success, `1` for runtime failure/partial success/cancellation, and `2` for invalid usage.\n\n## Multi-notebook retrieval\n\n`retrieve --nb` accepts comma-separated or repeated Notebook IDs, deduplicating up to 5 distinct notebooks:\n\n```sh\nqmind retrieve --nb nb-1,nb-2 \"What is the deployment process?\" --format json\nqmind retrieve --nb nb-1 --nb nb-2 \"What is the deployment process?\" --format agent\n```\n\n- Selection is explicit; the CLI never defaults to all accessible notebooks.\n- Multiple notebooks use one unified retrieval request. The server jointly retrieves and reranks Source chunks; output retains server ranking and each chunk/citation's `notebookId` and `notebookTitle`.\n- `--top-k` controls the joint recall candidate budget per route/query/channel; it is not multiplied by notebook count. `--max-results` limits the final results across all selected notebooks. Zero uses server defaults.\n- `--sources` requires a single notebook. A single deduplicated notebook keeps the existing retrieval endpoint. All retrieval output formats expose chunks and citations without knowledge cards.\n- Multi-notebook JSON returns `{ chunks, citations, promptContext, total, reranked }`. NDJSON emits one `kind: \"chunk\"` record per returned chunk, in server order; zero hits emit no records. Table and agent output also identify each evidence item's notebook.\n- Unified retrieval fails as one request when a target is invalid or inaccessible. The CLI reports the error without retrying notebooks individually or constructing partial-success results. Retrieval results no longer contain a `cards` field.\n\n## Directory synchronization\n\nReview the plan before allowing remote deletions:\n\n```sh\nqmind upload-folder --nb --dir ./docs --mode if-changed --dry-run\n```\n\nRemoving `--dry-run` enables writes. `--delete` treats the remote source root as a mirror of the local directory and removes extra remote entries. Concurrency must be between `1` and `10`.\n\n## Configuration and authentication\n\nThis package has a fixed Qoder Global identity. Renaming the executable, changing its install path, or setting product-selection environment variables cannot switch products. Production is the default; `--env test` and `--env daily` select supported debug presets. A custom target requires both `--sash` and `--dashboard` and cannot be combined with an explicit `--env`.\n\n```sh\nqmind login --env test\nQMIND_DEBUG_TOKEN='' qmind notebook list --env test --non-interactive --format json\nqmind login --sash http://localhost:8080 --dashboard http://localhost:3000\n```\n\nProduction token priority is `--token > QMIND_TOKEN > current production vault`. Debug token priority is `--token > QMIND_DEBUG_TOKEN > current debug vault`; credentials are never borrowed across targets.\n\nState is stored under `/cli/global//`, where the state root is `QMIND_HOME` or `~/.qmind`. The CLI does not install, load, or access the OS Keyring. Credential files are plaintext JSON, not encrypted storage. On POSIX, partition directories use mode `0700` and files use `0600`; these modes do not represent Windows ACLs. Writes use atomic replacement, file locking, and compare-and-swap protection for refreshes.\n\nAfter upgrading from the legacy unpartitioned store, sign in again. Root-level config/credential files, `~/.qmind-env`, and old Keyring entries are not read, imported, or deleted automatically.\n\nThe shared 3.x Global/CN release is a breaking upgrade from Global 2.x. Upgrade this package with npm, then run `qmind login`; do not copy legacy credentials into the new partition. Existing versions before the shared release describe the Global/shared implementation only and do not imply a historical CN publication.\n\nCommon variables include `QMIND_TOKEN`, `QMIND_DEBUG_TOKEN`, `QMIND_HOME`, `QMIND_CLIENT`, `QMIND_NON_INTERACTIVE`, `QMIND_REQUEST_TIMEOUT_MS`, `QMIND_STREAM_IDLE_TIMEOUT_MS`, and `QMIND_TLS_CA_FILE`. `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are supported. TLS verification is strict by default, and credentials are not forwarded to signed object-storage URLs.\n\n## Shared notebook discovery and access\n\n```sh\nqmind notebook list --shared --page 1 --page-size 20\nqmind notebook list --shared --format json\nqmind notebook get --format json\n```\n\nBoth notebook collections support `--page` and `--page-size`. `--shared` cannot be combined with `--filter-client`. Shared results use the same flat `notebooks` output as the ordinary list and preserve the membership `permission`. JSON/NDJSON preserve server-provided `access` (current role, member count and action permissions); Agent output expands these fields. Table lists show role and member count, while details show action permissions. Missing permissions are not inferred and display as `unknown` in tables.\n\n## Commands aligned with Agent tools\n\nCore-backed workflows (`notebook discover`, `source import-url/read/delete-batch`, `mkdir --derive-path`, `mv --to/--to-root`, unified retrieval, and `scheduled-task`) return `{ ok, data/error, meta }` after entering Agent Core, with `meta.operationId` identifying the operation. `--format ndjson` emits one complete result per line; `table` and `agent` also use this JSON result. CLI validation and host/credential failures before Core keep the existing CLI error format: `{ error }` on stdout for JSON/NDJSON, or text on stderr otherwise. Command usage errors and declined confirmations go to stderr. `source list --parent` keeps the existing Source-list output. Exit codes are 0 for success, 1 for partial success/runtime failure/cancellation, and 2 for invalid arguments. A successful write does not mean Source ingestion or a scheduled run has completed.\n\n```sh\n# Select retrieval-eligible owned/shared notebooks; continue with nextCursor when hasMore is true\nqmind notebook discover --relationship all --page-size 20\nqmind notebook discover --relationship all --cursor ''\n\n# Import a single page; inspect ingestion and content with source get / source read\nqmind source import-url --nb --url https://example.com/guide\nqmind source list --nb --parent \nqmind source read --nb --offset 0 --max-chars 20000\n\n# Derive paths from the actual parent and preserve the original basename when moving\nqmind source mkdir --nb --title guides --parent --derive-path\nqmind source mv --nb --to \nqmind source mv --nb --to-root\n\n# 1..100 distinct IDs; confirm interactively or explicitly pass --force\nqmind source delete-batch --nb --force\n```\n\n`notebook list/get` JSON/NDJSON preserve the server's overview, sourceCount and materialCount. Agent output expands summary/topics; table lists include summaries and Source counts. `discover` supports owned/shared/all and cursors, defaults to all, and lists retrieval-eligible notebooks; use `list` for the management collection. An empty page may still have `hasMore:true`; continue with the same relationship.\n\n`source read` checks ingestion status and returns `content/contentType/truncated/nextOffset`. It still fetches the entire body before slicing, so only output size is bounded. Existing `source content` full-text/download behavior is unchanged. `source list --parent` cannot be combined with `--all`.\n\n`mkdir --derive-path` conflicts with `--path`. `mv --to/--to-root` conflicts with the legacy parent/path/rename/status options and only moves eligible leaf documents within one notebook, preserving the basename. Existing low-level mkdir/mv patch operations remain available.\n\nBatch deletion returns the submitted sourceIds and successCount/failureCount; sourceIds is not a list of successfully deleted IDs. Partial failure exits 1. Reconcile current state before another call; do not guess failed IDs or replay the entire batch.\n\n## Precise and unified retrieval\n\nExisting `retrieve --nb` defaults and output remain unchanged. Explicit `--unified` or `--targets` selects the same unified retrieval workflow used by Agent tools, including notebook identity in single-notebook chunks:\n\n```sh\nqmind retrieve --nb --unified --score-threshold 0.6 'Deployment process'\nqmind retrieve --targets '[{\"notebookId\":\"nb-1\",\"sourceIds\":[\"source-1\"]},{\"notebookId\":\"nb-2\",\"sourceIds\":[\"source-2\"]}]' --max-results 8 'Deployment process'\n```\n\n`--targets` conflicts with `--nb` and `--sources` and supports independent Source filters per notebook. Unified retrieval defaults to maxResults=8 (1..50), with optional topK (1..100); zero selects the workflow default. There may be at most five unique targets. Results use the envelope above: read `data.chunks/data.promptContext`. `--score-threshold` accepts 0..1 and also works on the existing retrieval path. Zero budgets on the existing path still use server defaults; scripts are not silently migrated.\n\n## Scheduled task configuration\n\n```sh\nqmind scheduled-task create --nb --scene source_refresh --schedule 'CRON_TZ=Asia/Shanghai 0 9 * * *'\nqmind scheduled-task list --nb --enabled true --page 1 --page-size 20\nqmind scheduled-task update --nb --schedule 'CRON_TZ=Asia/Shanghai 0 10 * * *'\nqmind scheduled-task pause --nb \nqmind scheduled-task resume --nb \nqmind scheduled-task delete --nb \n```\n\n`update --enabled false/true` also pauses/resumes. Creation defaults to enabled with empty config; arbitrary prompt/config inputs are not accepted. Updates only change schedule or enabled. Scenes are compilation, condensation, lint, source_refresh and source_binding_sync; the server decides actual availability and full Cron validity. An explicit IANA timezone is required. Compilation may be retired; source_binding_sync is currently a per-notebook singleton with a minimum five-minute interval. `list` supports `--task/--scene/--enabled`, with pageSize at most 20; the backend still reads all configurations for the notebook. Oversized config is marked `configTruncated:true`.\n\nConfiguration is separate from execution: use `task list --scheduled-task ` for run history. Pausing/deleting does not cancel dispatched runs; resuming an overdue schedule may trigger a run immediately. Execution retains the original creator identity; revoking membership does not guarantee schedules stop automatically.\n\n## Unconfirmed writes\n\nWhen a new command returns `error.code=outcome_unknown` and `retryable:false`, inspect current state before deciding what to do next; do not retry automatically. Existing direct-write commands also distinguish this state in JSON/NDJSON errors and retain the original causeCode/requestId. Unknown outcomes do not prove a request reached the server; a same-name resource does not prove this call created it.\n\n`notebook delete` and `source delete` support JSON/NDJSON success receipts. Single-Source deletion stops if preflight cannot read the Source; only explicit `--force` skips directory confirmation. Default text output remains `deleted`.\n", "readmeFilename": "README.md" }