@evatick/cli 0.4.0 → 0.4.2

package/README.md

@@ -1,7 +1,13 @@
-# EVA CLI
+# EVA Tick CLI
 
-EVA CLI is a stable, machine-readable market-data command-line client for LLMs,
-AI agents, and automation. It connects to the versioned EVA HTTP API.
+Deterministic, machine-readable financial data for AI agents, LLMs, and
+automation.
+
+EVA Tick gives agents canonical instrument IDs, stable JSON, structured errors,
+and predictable commands instead of provider-specific identifiers and
+functions.
+
+![Codex queries financial data through EVA Tick](https://raw.githubusercontent.com/xiaochaohit/evatick-cli/main/docs/assets/eva-tick-codex-demo.gif)
 
 ## Install
 
@@ -10,17 +16,84 @@ npm install --global @evatick/cli
 eva version
 ```
 
-It can also be run without a global installation:
+Run it without installing:
 
 ```shell
 npx @evatick/cli health
 ```
 
-The npm package is implemented in Node.js and has no runtime dependencies.
-Python and platform-specific native executables are not required.
+The npm package is implemented in Node.js, has no runtime dependencies, and
+does not require Python or platform-specific native executables.
+
+## First query
+
+```shell
+eva health
+eva instrument search --query 平安银行 --type equity --limit 3
+eva instrument resolve --query 000001 --type equity
+eva stock bars --symbol cn:equity:XSHE:000001 \
+  --interval 1d \
+  --start 2026-08-18 \
+  --end 2026-08-21 \
+  --adjustment forward \
+  --limit 3
+```
+
+## Common commands
+
+- `eva instrument search` finds canonical financial instruments by name, code,
+  or alias.
+- `eva stock bars` queries normalized OHLCV bars.
+- `eva index constituents` queries index constituent memberships.
+- `eva futures bars` queries official mainland China futures daily bars.
+- `eva crypto quotes` queries one explicitly selected cryptocurrency exchange.
+
+Run `eva COMMAND --help` or `eva GROUP COMMAND --help` for supported options.
+
+## Hosted or self-hosted
+
+The CLI connects to the hosted EVA Tick service at `https://api.evatick.com` by
+default. Point it at a self-hosted [EVA Tick Server](https://github.com/xiaochaohit/evatick-server)
+temporarily with an environment variable:
+
+```shell
+EVA_SERVER_URL=http://127.0.0.1:8765 eva health
+```
+
+Or save the service URL:
+
+```shell
+eva config set --base-url http://127.0.0.1:8765
+eva config show
+```
+
+When a service requires authentication, use `EVA_API_KEY` or
+`eva config set --api-key 'eva_...'`. The CLI sends a key only when configured,
+and `eva config show` masks stored keys.
+
+## Current availability
+
+EVA Tick is designed as a provider-independent financial data layer. The
+current public service covers mainland China A-shares; SSE, SZSE, and CSI
+indices; CFFEX, SHFE, INE, and CZCE futures; and exchange-scoped Binance and
+Coinbase cryptocurrency markets. Availability varies by deployed service and
+enabled providers.
+
+## Output and safety
+
+- Successful results are compact JSON on stdout.
+- Failures are structured JSON on stderr with stable error codes.
+- JSON, JSONL, and CSV file exports are supported by the npm CLI.
+- Existing files are never overwritten unless `--overwrite` is explicit.
+- Parquet export is available in the Python distribution with
+  `pip install 'evatick[parquet]'`.
+
+## Documentation
 
-JSON, JSONL, and CSV exports are supported. Parquet export remains available in
-the Python distribution (`pip install 'evatick[parquet]'`).
+- [Complete CLI documentation and examples](https://github.com/xiaochaohit/evatick-cli#readme)
+- [EVA Tick Skill for Codex](https://www.npmjs.com/package/@evatick/skill)
+- [Self-hosted server and OpenAPI contract](https://github.com/xiaochaohit/evatick-server)
+- [License and data-source notices](https://github.com/xiaochaohit/evatick-cli#license)
 
-See the [EVA CLI repository](https://github.com/xiaochaohit/evatick-cli) for
-commands, configuration, source code, and license information.
+Market data is provided for research and reference only and does not constitute
+investment advice.

package/lib/cli.js

@@ -19,7 +19,7 @@ const ROOT_HELP = `NAME
     eva
 
 PURPOSE
-    通过 EVA 查询股票和指数数据。
+    通过 EVA 查询股票、指数、中国期货和交易所加密货币数据。
 
 USAGE
     eva [--config PATH] [--server-url URL] [--api-key KEY] COMMAND [OPTIONS]
@@ -31,6 +31,8 @@ OPTIONS
 
 COMMANDS
     config
+    crypto
+    futures
     health
     index
     instrument
@@ -45,16 +47,22 @@ const HELP = {
   health: "Usage: eva health [OPTIONS]\n\nOptions:\n  --timeout FLOAT  [default: 10]\n  --retries INTEGER  [default: 0]\n  --help\n",
   version: "Usage: eva version [OPTIONS]\n\nOptions:\n  --help\n",
   instrument: "Usage: eva instrument [OPTIONS] COMMAND [ARGS]...\n\n  Discover and resolve canonical instruments.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  list\n  resolve\n  search\n  show\n",
-  "instrument list": "Usage: eva instrument list [OPTIONS]\n\nOptions:\n  --type [equity|index]\n  --venue TEXT\n  --publisher TEXT\n  --capability [quote|bars|constituents]\n  --cursor TEXT\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
-  "instrument search": "Usage: eva instrument search [OPTIONS]\n\nOptions:\n  --query TEXT  [required]\n  --type [equity|index]\n  --venue TEXT\n  --publisher TEXT\n  --capability [quote|bars|constituents]\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
-  "instrument resolve": "Usage: eva instrument resolve [OPTIONS]\n\nOptions:\n  --query TEXT  [required]\n  --type [equity|index]\n  --venue TEXT\n  --publisher TEXT\n  --capability [quote|bars|constituents]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "instrument list": "Usage: eva instrument list [OPTIONS]\n\nOptions:\n  --type [equity|index|future|crypto]\n  --venue TEXT\n  --publisher TEXT\n  --capability [quote|bars|constituents]\n  --cursor TEXT\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "instrument search": "Usage: eva instrument search [OPTIONS]\n\nOptions:\n  --query TEXT  [required]\n  --type [equity|index|future|crypto]\n  --venue TEXT\n  --publisher TEXT\n  --capability [quote|bars|constituents]\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "instrument resolve": "Usage: eva instrument resolve [OPTIONS]\n\nOptions:\n  --query TEXT  [required]\n  --type [equity|index|future|crypto]\n  --venue TEXT\n  --publisher TEXT\n  --capability [quote|bars|constituents]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
   "instrument show": "Usage: eva instrument show [OPTIONS]\n\nOptions:\n  --id TEXT  [required]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
   stock: "Usage: eva stock [OPTIONS] COMMAND [ARGS]...\n\n  Query mainland A-share data.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  bars\n  quotes\n",
   index: "Usage: eva index [OPTIONS] COMMAND [ARGS]...\n\n  Query SSE, SZSE, and CSI index data.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  bars\n  constituents\n  quotes\n",
+  futures: "Usage: eva futures [OPTIONS] COMMAND [ARGS]...\n\n  Query mainland China futures contracts.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  bars\n  quotes\n",
+  crypto: "Usage: eva crypto [OPTIONS] COMMAND [ARGS]...\n\n  Query exchange-scoped cryptocurrency market data.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  bars\n  quotes\n",
   "stock quotes": "Usage: eva stock quotes [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
   "index quotes": "Usage: eva index quotes [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
-  "stock bars": "Usage: eva stock bars [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --interval [1m|5m|15m|30m|60m|1d|1w|1mo]  [default: 1d]\n  --start TEXT\n  --end TEXT\n  --adjustment [none|forward|backward]  [default: none]\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
-  "index bars": "Usage: eva index bars [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --interval [1m|5m|15m|30m|60m|1d|1w|1mo]  [default: 1d]\n  --start TEXT\n  --end TEXT\n  --adjustment [none|forward|backward]  [default: none]\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "futures quotes": "Usage: eva futures quotes [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "crypto quotes": "Usage: eva crypto quotes [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --venue [BINANCE|COINBASE]  [required]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "stock bars": "Usage: eva stock bars [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --interval [1m|5m|15m|30m|60m|1d|1w|1mo]  [default: 1d]\n  --start TEXT\n  --end TEXT\n  --adjustment [none|forward|backward]  [default: none]\n  --as-of TEXT\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "index bars": "Usage: eva index bars [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --interval [1m|5m|15m|30m|60m|1d|1w|1mo]  [default: 1d]\n  --start TEXT\n  --end TEXT\n  --adjustment [none|forward|backward]  [default: none]\n  --as-of TEXT\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "futures bars": "Usage: eva futures bars [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --interval [1m|5m|15m|30m|60m|1d|1w|1mo]  [default: 1d]\n  --start TEXT\n  --end TEXT\n  --adjustment [none|forward|backward]  [default: none]\n  --as-of TEXT\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "crypto bars": "Usage: eva crypto bars [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --venue [BINANCE|COINBASE]  [required]\n  --interval [1m|5m|15m|30m|60m|1d|1w|1mo]  [default: 1d]\n  --start TEXT\n  --end TEXT\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
   "index constituents": "Usage: eva index constituents [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --as-of TEXT\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
 };
 
@@ -75,7 +83,7 @@ const dataDefinitions = {
   ...requestDefinitions,
 };
 const discoveryDefinitions = {
-  type: { type: "choice", choices: ["equity", "index"] },
+  type: { type: "choice", choices: ["equity", "index", "future", "crypto"] },
   venue: { type: "string" },
   publisher: { type: "string" },
   capability: { type: "choice", choices: ["quote", "bars", "constituents"] },
@@ -316,13 +324,15 @@ async function dispatch(context, command, subcommand, arguments_) {
     process.stdout.write(`${dumps(response.data ?? {})}\n`);
     return;
   }
-  if (key === "stock quotes" || key === "index quotes") {
+  if (key === "stock quotes" || key === "index quotes" || key === "futures quotes" || key === "crypto quotes") {
     const options = parseOptions(arguments_, {
-      symbol: { type: "string" }, ...requestDefinitions,
-    }, ["symbol"]);
-    const instrumentType = command === "stock" ? "equity" : "index";
+      symbol: { type: "string" },
+      ...(command === "crypto" ? { venue: { type: "choice", choices: ["BINANCE", "COINBASE"] } } : {}),
+      ...requestDefinitions,
+    }, command === "crypto" ? ["symbol", "venue"] : ["symbol"]);
+    const instrumentType = command === "stock" ? "equity" : command === "index" ? "index" : command === "futures" ? "future" : "crypto";
     const http = client(context, options);
-    const instrumentId = await http.resolve(options.symbol, instrumentType, "quote");
+    const instrumentId = await http.resolve(options.symbol, instrumentType, "quote", options.venue);
     const response = await http.request(
       "GET",
       `/v1/instruments/${encodeURIComponent(instrumentId)}/quote`,
@@ -330,25 +340,30 @@ async function dispatch(context, command, subcommand, arguments_) {
     process.stdout.write(`${dumps(response.data ?? {})}\n`);
     return;
   }
-  if (key === "stock bars" || key === "index bars") {
+  if (key === "stock bars" || key === "index bars" || key === "futures bars" || key === "crypto bars") {
     const options = parseOptions(arguments_, {
       symbol: { type: "string" },
+      ...(command === "crypto" ? { venue: { type: "choice", choices: ["BINANCE", "COINBASE"] } } : {}),
       interval: { type: "choice", choices: INTERVALS, default: "1d" },
       start: { type: "string" },
       end: { type: "string" },
-      adjustment: { type: "choice", choices: ["none", "forward", "backward"], default: "none" },
+      ...(command === "crypto" ? {} : {
+        adjustment: { type: "choice", choices: ["none", "forward", "backward"], default: "none" },
+        "as-of": { type: "string" },
+      }),
       ...dataDefinitions,
-    }, ["symbol"]);
-    const instrumentType = command === "stock" ? "equity" : "index";
+    }, command === "crypto" ? ["symbol", "venue"] : ["symbol"]);
+    const instrumentType = command === "stock" ? "equity" : command === "index" ? "index" : command === "futures" ? "future" : "crypto";
     const http = client(context, options);
-    const instrumentId = await http.resolve(options.symbol, instrumentType, "bars");
+    const instrumentId = await http.resolve(options.symbol, instrumentType, "bars", options.venue);
     const response = await http.request(
       "GET",
       `/v1/instruments/${encodeURIComponent(instrumentId)}/bars?${queryString({
         interval: options.interval,
         start: options.start,
         end: options.end,
-        adjustment: options.adjustment,
+        adjustment: options.adjustment || "none",
+        as_of: options.asOf,
       })}`,
     );
     emit(response.data ?? [], options);
@@ -374,7 +389,7 @@ async function dispatch(context, command, subcommand, arguments_) {
 function commandParts(remaining) {
   const command = remaining[0];
   if (!command) return {};
-  if (!["config", "health", "version", "instrument", "stock", "index"].includes(command)) {
+  if (!["config", "health", "version", "instrument", "stock", "index", "futures", "crypto"].includes(command)) {
     throw usage(`No such command '${command}'.`);
   }
   if (["health", "version"].includes(command)) {
@@ -389,6 +404,8 @@ function commandParts(remaining) {
     instrument: ["list", "search", "resolve", "show"],
     stock: ["quotes", "bars"],
     index: ["quotes", "bars", "constituents"],
+    futures: ["quotes", "bars"],
+    crypto: ["quotes", "bars"],
   }[command];
   if (!valid.includes(subcommand)) throw usage(`No such command '${subcommand}'.`);
   return { command, subcommand, arguments_: remaining.slice(2) };

package/lib/http-client.js

@@ -91,10 +91,20 @@ class EvaHttpClient {
     throw new Error("HTTP retry loop exhausted");
   }
 
-  async resolve(query, instrumentType, capability) {
+  async resolve(query, instrumentType, capability, venue) {
+    const canonicalParts = query.split(":", 4);
+    if (
+      canonicalParts.length === 4 &&
+      canonicalParts[1] === instrumentType &&
+      (!venue || canonicalParts[2].toUpperCase() === venue.toUpperCase())
+    ) return query;
     const response = await this.request("POST", "/v1/instrument-resolve", {
       query,
-      context: { instrument_type: instrumentType, capability },
+      context: {
+        instrument_type: instrumentType,
+        capability,
+        ...(venue ? { venue } : {}),
+      },
     });
     const data = response.data || {};
     const instrumentId = data.instrument && data.instrument.instrument_id;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@evatick/cli",
-  "version": "0.4.0",
-  "description": "EVA market data command-line client for LLMs, agents, and automation",
+  "version": "0.4.2",
+  "description": "EVA Tick CLI for deterministic, machine-readable financial data queries by AI agents, LLMs, and automation",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,5 +23,19 @@
   ],
   "engines": {
     "node": ">=18"
-  }
+  },
+  "keywords": [
+    "eva-tick",
+    "financial-data",
+    "market-data",
+    "ai-agent",
+    "llm",
+    "codex",
+    "automation",
+    "quantitative-finance",
+    "openapi",
+    "akshare",
+    "a-share",
+    "china-stock-market"
+  ]
 }