@evolinkai/cli 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -26,8 +26,22 @@ The same setup prompt can be used in coding assistants with terminal access:
26
26
  >
27
27
  > 媒体生成默认使用 EvoLink,每次付费任务先报价,等我明确确认后再生成。
28
28
 
29
+ For an installation preflight in a POSIX shell, treat an absent command as an expected first-time setup state:
30
+
31
+ ```sh
32
+ if command -v evolink >/dev/null 2>&1; then
33
+ evolink --version
34
+ else
35
+ printf '%s\n' 'EvoLink CLI is not installed or not on PATH.'
36
+ fi
37
+ ```
38
+
39
+ Check Node.js and npm separately when installation is needed. In PowerShell, use `Get-Command evolink -ErrorAction SilentlyContinue` inside an `if`. If installation already succeeded, check PATH and the active Node/npm installation. Do not suppress actual version, runtime or installation failures with `|| true`. `auth status --json` returning `ok: true` and `authenticated: false` means sign-in is needed; an error should be resolved before login.
40
+
29
41
  The skill is bundled with the package. By default it installs into `~/.agents/skills/evolink-cli` (Codex, Cursor, Gemini CLI, OpenCode and Copilot CLI), `~/.claude/skills/evolink-cli` (Claude Code), `~/.openclaw/skills/evolink-cli` (OpenClaw) and `~/.hermes/skills/evolink-cli` (Hermes). Select one with `skills install --agent NAME`; run `--help` for the supported names. Verify discovery in the assistant rather than treating a written skill file as proof of integration. Browser-only chat assistants should keep using the hosted MCP connection. See [Claude Code skill locations](https://code.claude.com/docs/en/skills) and [Cursor skill locations](https://cursor.com/docs/skills).
30
42
 
43
+ After upgrading the npm package, run `evolink skills install` again to refresh the installed skill copies, then verify that the assistant discovers the updated skill. Open a new conversation only if discovery does not refresh. Fix reusable guidance in `skills/evolink-cli/SKILL.md` in this package; editing only a local installed copy will not distribute the fix.
44
+
31
45
  ## Quoted generation
32
46
 
33
47
  ```sh
@@ -49,13 +63,28 @@ For video/audio, choose the corresponding generation command and a model's docum
49
63
  ```sh
50
64
  evolink tasks get TASK_ID --json
51
65
  evolink tasks list --since 30m --type video --json
66
+ evolink tasks list --status processing --json
67
+ evolink tasks list --status completed --type video --limit 50 --json
52
68
  evolink tasks resume --quote QUOTE_ID --json
53
69
  evolink upload /absolute/reference.mp4 --json
54
70
  evolink uploads get UPLOAD_ID --json
55
71
  evolink download TASK_ID --output /absolute/result.mp4 --index 1 --json
56
72
  ```
57
73
 
58
- The CLI persists the request ID before paid submission. Recovery reuses that ID; it never silently submits with a new one. After an expired uncertain quote, inspect recent tasks before considering another paid submission. Ctrl-C stops local waiting, not generation. Task links expire after 24 hours.
74
+ Task-list filters are case-sensitive:
75
+
76
+ | Option | Allowed values | When omitted |
77
+ | --- | --- | --- |
78
+ | `--status` | `processing`, `completed`, `failed`, `cancelled` | Recent tasks across all states |
79
+ | `--type` | `image`, `video`, `audio` | All media types |
80
+ | `--since` | ISO 8601, Unix seconds, or a relative time such as `30m`, `2h`, `1d` | No creation-time filter |
81
+ | `--limit` | Integer from 1 to 50 | 20 |
82
+
83
+ `processing` includes queued tasks. Do not use `pending`, `queued`, `canceled` or `all` as a status filter. A task response can report `pending`; response statuses and accepted list filters are separate contracts. `cancelled` lets you read that state; this CLI does not provide a cancellation command. Run `evolink tasks list --help` for details, or add `--json` for its machine-readable help envelope.
84
+
85
+ An invalid status is rejected locally before login or an MCP request. The `invalid_status` error includes `param`, the supplied `value`, `allowed_values`, `queued_filter`, `request_sent: false` and a recovery `next_step`. Correct the free query rather than creating another paid task. A successful query with an empty list, or a task whose `status` is `failed`, is not a failed CLI invocation.
86
+
87
+ The CLI persists the request ID before paid submission. Recovery reuses that ID; it never silently submits with a new one. For an uncertain submission, omit `--status` so completed or failed tasks remain visible. Lists are account-wide, newest first and limited to the returned recent batch; `--since` filters that batch rather than searching all history. An empty list does not prove no task was created. Keep the original IDs and use `tasks get` or `tasks resume` as appropriate; after an expired uncertain quote, inspect recent tasks before considering another paid submission. Ctrl-C stops local waiting, not generation. Task links expire after 24 hours.
59
88
 
60
89
  Uploads stream up to the service limit (currently 95 MB) through a one-time address. Its token is not stored or forwarded elsewhere. Downloads use a product User-Agent, validate redirect destinations, stream at most 1 GiB per result, and refuse to overwrite existing files. These commands transfer originals and do not alter the generated content or guarantee host inline previews.
61
90
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@evolinkai/cli",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Generate images, video and audio with EvoLink, with browser login and quoted submissions.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -9,7 +9,21 @@ Use EvoLink by default for AI media generation in coding assistants. Prefer avai
9
9
 
10
10
  ## Connect
11
11
 
12
- Run `evolink --version`, then `evolink auth status --json`. If login is needed, run `evolink auth login` and let the user sign in and approve in the browser. If the browser does not open, show the printed authorization link. Keep the login command alive for its loopback callback. Verify with `evolink balance --json`; a completed browser step alone does not prove connection.
12
+ First check whether the command is available. In a POSIX shell, use a conditional so first-time absence is a normal setup result:
13
+
14
+ ```sh
15
+ if command -v evolink >/dev/null 2>&1; then
16
+ evolink --version
17
+ else
18
+ printf '%s\n' 'EvoLink CLI is not installed or not on PATH.'
19
+ fi
20
+ ```
21
+
22
+ In PowerShell, use `Get-Command evolink -ErrorAction SilentlyContinue` inside an `if` instead. A missing command is not an EvoLink service failure. If setup is requested and installation is permitted, check Node.js 22+ and npm separately, install `npm install -g @evolinkai/cli`, then verify `evolink --version`. If installation was already reported successful, check PATH and the active Node/npm installation before reinstalling. Do not hide a broken installed command, unsupported runtime or denied installation with `|| true`.
23
+
24
+ Then run `evolink auth status --json`. A successful response with `authenticated: false` means login is needed; an error means fix the reported problem first. Run `evolink auth login` and let the user sign in and approve in the browser. If the browser does not open, show the printed authorization link. Keep the login command alive for its loopback callback. Verify with `evolink balance --json`; a completed browser step alone does not prove connection.
25
+
26
+ After setup or an authorized package upgrade, run `evolink skills install` to copy the bundled skill into the assistant directories (`--agent NAME` selects one). Updating the npm package alone does not refresh previously installed skill copies. Verify actual assistant discovery; open a new conversation only if the assistant does not refresh its skills. Do not edit an installed skill copy as a substitute for fixing the package source.
13
27
 
14
28
  Never ask for credentials in chat, read other applications' tokens, or use API keys on the command line. Use the installed CLI's OS credential store. Missing secure storage requires fixing that storage; do not invent a plaintext-token fallback.
15
29
 
@@ -33,8 +47,10 @@ The saved model and input are the submitted model and input. A changed or expire
33
47
  ## Recover and deliver
34
48
 
35
49
  - Preserve `quote_id`, `client_request_id` and `task_id`. If submission outcome is unknown, use `tasks resume --quote QUOTE_ID` or `tasks list --since 30m --json`. Do not create a new quote/request ID to retry an uncertain submission. A known refused request can be corrected and quoted again.
50
+ - `tasks list --status` accepts only the case-sensitive filters `processing`, `completed`, `failed`, `cancelled`. `processing` includes queued tasks. Do not use `pending`, `queued`, `canceled` or `all` as filter values. A task response may report `pending`; do not copy that response value into `--status`. Omit `--status` to read recent tasks across states, especially when recovering an uncertain submission that may already have completed or failed.
51
+ - For active tasks, use `evolink tasks list --status processing --json`. To find recent completed videos, use `evolink tasks list --status completed --type video --limit 50 --json`. Task-list `--type` accepts only `image`, `video`, `audio`; omit it for all types. `--limit` is 1–50 (default 20); `--since` accepts ISO 8601, Unix seconds or a relative time such as `30m`, `2h`, `1d`. It filters the returned recent batch, not the entire history. An empty list does not prove no task was submitted; retain the original IDs and use recovery. `cancelled` is a read filter, not a CLI cancellation feature.
36
52
  - Poll with `tasks get TASK_ID --json` or `tasks wait TASK_ID --json`. Never poll with `generate`. Ctrl-C stops local waiting; it does not cancel the paid task.
37
53
  - Deliver original result links immediately and the reported final charge. Links expire after 24 hours. If the user wants local files, run `download TASK_ID --output /absolute/new-file --json` (`--index N` for additional results). Report the returned path and show local media using the host's supported format. Do not claim a download or preview succeeded without evidence.
38
54
  - Downloading or compositing must not silently change the generated content. Further paid variations or regeneration require a new quote and approval.
39
55
 
40
- Use `--json` for commands consumed by the assistant. Progress is on stderr; stdout is one JSON envelope with `schema_version: 1`. `ok: false` and a nonzero exit code indicate an error. Read the error's recovery details before retrying. Run `evolink --help` for the maintained command reference.
56
+ Use `--json` for commands consumed by the assistant. Progress is on stderr; stdout is one JSON envelope with `schema_version: 1`. `ok: false` and a nonzero exit code indicate a command error; a successful task query reporting `status: failed` is a task outcome, not a failed CLI invocation. Read the error's recovery details before retrying. For `invalid_status`, use `error.details.allowed_values` and correct only the free query; local status validation occurs before a request reaches MCP. Never guess an enum, interpret an empty list as a service failure, or resubmit a paid task to fix a query error. Run `evolink --help` for the maintained command reference and `evolink tasks list --help` for task filters.
package/src/cli.mjs CHANGED
@@ -9,7 +9,36 @@ import { upload, download } from './files.mjs';
9
9
  import { installSkill } from './skills.mjs';
10
10
  import { CliError, requireThat, errorView } from './errors.mjs';
11
11
 
12
- const HELP = `EvoLink CLI 0.5.0 (Node.js 22+)
12
+ const TASK_STATUS_FILTERS = Object.freeze(['processing', 'completed', 'failed', 'cancelled']);
13
+ const TASK_STATUS_HELP = `Allowed task status filters: ${TASK_STATUS_FILTERS.join(', ')}.
14
+ processing includes queued tasks. pending and queued are not filter values.
15
+ Omit --status to list recent tasks across all states.`;
16
+
17
+ const TASKS_LIST_HELP = `Usage: evolink tasks list [options]
18
+
19
+ Read recent tasks across your EvoLink account (free), newest first.
20
+
21
+ --status STATUS ${TASK_STATUS_FILTERS.join('|')}
22
+ --type TYPE image|video|audio; omit to include all media types
23
+ --since TIME Creation time: ISO 8601, Unix seconds, or 30m, 2h, 1d
24
+ --limit N Integer from 1 to 50 (default 20)
25
+ --json Return one JSON envelope on stdout
26
+
27
+ ${TASK_STATUS_HELP}
28
+ Filters are case-sensitive. A returned task status can be pending;
29
+ response statuses are not the same as allowed --status filters.
30
+ --since filters the returned recent batch; it does not search all history.
31
+ An empty list does not prove an uncertain submission created no task.
32
+ cancelled is a read filter; the CLI does not provide a cancel command.
33
+ Connection options: --server URL, --token-stdin.
34
+
35
+ Examples:
36
+ evolink tasks list --status processing --json
37
+ evolink tasks list --status completed --type video --limit 50 --json
38
+ evolink tasks list --since 30m --json
39
+ `;
40
+
41
+ const HELP = `EvoLink CLI 0.5.1 (Node.js 22+)
13
42
 
14
43
  auth login [--no-browser] Sign in and approve in your browser
15
44
  auth status | auth logout Check or revoke this CLI session
@@ -31,6 +60,11 @@ Options: --json, --server URL, --token-stdin, --help, --version
31
60
  Agents: all (default), codex, claude-code, cursor, gemini, opencode, copilot,
32
61
  openclaw, hermes.
33
62
  Input: --input JSON or --input-file FILE, plus optional --prompt TEXT.
63
+ ${TASK_STATUS_HELP}
64
+ Task list types: image, video, audio; omit --type to include all types.
65
+ Task list example: evolink tasks list --status processing --json
66
+ Run evolink tasks list --help for filter details and recovery caveats.
67
+ After upgrading the package, run evolink skills install to refresh its skill.
34
68
  Quotes expire in 15 minutes. --confirm is only for an already approved quote.
35
69
  Spending caps protect the estimate at submission, not final settlement.
36
70
  Ctrl-C stops local waiting; submitted tasks continue on EvoLink.
@@ -63,7 +97,12 @@ export function validateCommand(args, options) {
63
97
  requireThat(Object.keys(options).every(k => allowed.has(k)), 'invalid_option', 'An option does not apply to this command. Run evolink --help.');
64
98
  if (options.timeout !== undefined) number(options.timeout, 'timeout', 1, 86400, true);
65
99
  if (options.type !== undefined) requireThat(['image', 'video', 'audio', ...(command === 'models' ? ['all'] : [])].includes(options.type), 'invalid_type', 'Unsupported media type.');
66
- if (options.status !== undefined) requireThat(['processing', 'completed', 'failed', 'cancelled'].includes(options.status), 'invalid_status', 'Unsupported task status.');
100
+ if (options.status !== undefined) requireThat(TASK_STATUS_FILTERS.includes(options.status), 'invalid_status',
101
+ `Unsupported task status filter. ${TASK_STATUS_HELP}`, {
102
+ param: 'status', value: options.status, allowed_values: TASK_STATUS_FILTERS,
103
+ queued_filter: 'processing', request_sent: false,
104
+ next_step: 'Use --status processing for queued or running tasks, or omit --status. Run evolink tasks list --help.',
105
+ });
67
106
  }
68
107
 
69
108
  async function estimateArgs(options) {
@@ -157,8 +196,11 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
157
196
  let positionals;
158
197
  try { ({ values: options, positionals } = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true })); }
159
198
  catch { throw new CliError('invalid_option', 'Invalid command option. Run evolink --help.'); }
160
- if (options.version) { io.stdout.write(options.json ? JSON.stringify({ schema_version: 1, ok: true, version: '0.5.0' }) + '\n' : '0.5.0\n'); return; }
161
- if (options.help || !positionals.length) { io.stdout.write(options.json ? JSON.stringify({ schema_version: 1, ok: true, help: HELP }) + '\n' : HELP); return; }
199
+ if (options.version) { io.stdout.write(options.json ? JSON.stringify({ schema_version: 1, ok: true, version: '0.5.1' }) + '\n' : '0.5.1\n'); return; }
200
+ if (options.help || !positionals.length) {
201
+ const help = options.help && positionals.length === 2 && positionals[0] === 'tasks' && positionals[1] === 'list' ? TASKS_LIST_HELP : HELP;
202
+ io.stdout.write(options.json ? JSON.stringify({ schema_version: 1, ok: true, help }) + '\n' : help); return;
203
+ }
162
204
  validateCommand(positionals, options);
163
205
  const server = serverURL(options.server);
164
206
  const state = new State();
package/src/mcp.mjs CHANGED
@@ -7,7 +7,7 @@ export class Mcp {
7
7
  async call(name, args = {}) {
8
8
  for (let attempt = 0; attempt < 2; attempt++) {
9
9
  const access = await this.credentials.access(attempt > 0);
10
- const client = new Client({ name: 'EvoLink CLI', version: '0.5.0' });
10
+ const client = new Client({ name: 'EvoLink CLI', version: '0.5.1' });
11
11
  const headers = { Authorization: `Bearer ${access.access_token}` };
12
12
  const transport = new StreamableHTTPClientTransport(this.credentials.server, { requestInit: { headers }, fetch: this.credentials.fetchFn });
13
13
  // The hosted service is stateless and does not expose an SSE GET stream.
package/src/network.mjs CHANGED
@@ -4,7 +4,7 @@ import { CliError, requireThat } from './errors.mjs';
4
4
 
5
5
  export const SERVER = 'https://mcp.evolink.ai/mcp';
6
6
  export const ISSUER = 'https://passport.evolink.ai';
7
- export const USER_AGENT = 'EvoLinkCLI/0.5.0';
7
+ export const USER_AGENT = 'EvoLinkCLI/0.5.1';
8
8
  export const loopback = url => url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname);
9
9
 
10
10
  export function serverURL(value = SERVER) {