@evolinkai/cli 0.5.1 → 0.7.0
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 +83 -1
- package/package.json +1 -1
- package/skills/evolink-cli/SKILL.md +27 -3
- package/skills/evolink-cli/references/capabilities.md +38 -0
- package/skills/evolink-cli/references/media-workflows.md +25 -0
- package/skills/evolink-cli/references/usage-and-budget.md +17 -0
- package/src/auth.mjs +28 -9
- package/src/cli.mjs +111 -31
- package/src/doctor.mjs +66 -0
- package/src/errors.mjs +25 -1
- package/src/files.mjs +122 -10
- package/src/help.mjs +68 -0
- package/src/mcp.mjs +10 -2
- package/src/media-content.mjs +31 -0
- package/src/media.mjs +40 -10
- package/src/network.mjs +55 -17
- package/src/setup.mjs +69 -0
- package/src/skills.mjs +159 -22
- package/src/state.mjs +64 -25
- package/src/version.mjs +3 -0
package/README.md
CHANGED
|
@@ -42,6 +42,32 @@ The skill is bundled with the package. By default it installs into `~/.agents/sk
|
|
|
42
42
|
|
|
43
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
44
|
|
|
45
|
+
## Setup and skill updates
|
|
46
|
+
|
|
47
|
+
Starting with CLI 0.6.0, use the selected assistant's name:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
evolink setup --agent codex --json
|
|
51
|
+
evolink skills status --agent codex --json
|
|
52
|
+
evolink doctor --agent codex --json
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`setup` checks Node.js, writable state and credential storage, synchronizes the selected skill, reuses an existing login only after checking the real account connection, and verifies model discovery. When needed it waits for browser approval. Repeating setup reuses completed steps; connection errors do not automatically trigger a new login. Checks submit no paid media tasks. The default agent is `all`; use `--agent` to install only for the assistant you are using. Commands sharing a state directory serialize setup; skill writes also serialize across state directories in the same home.
|
|
56
|
+
|
|
57
|
+
CLI checks cannot prove that the assistant has loaded a skill. A successful result leaves `assistant_discovery: not_checked`; ask the assistant to confirm discovery in the current conversation. Reopen only when the assistant cannot refresh. A failed stage returns its error and a setup recovery command without erasing completed installations.
|
|
58
|
+
|
|
59
|
+
`auth login` and `setup` accept `--timeout SECONDS` (30–900, default 180). Keep the login process running until it reports completion. If it times out or is interrupted, start a new login and open the new link. The local callback page acknowledges receipt and returns you to the assistant for verification; it does not claim the account connection was verified. Repeated callbacks are refused and the browser page clears the authorization query from its visible URL.
|
|
60
|
+
|
|
61
|
+
The installer copies SKILL.md and its bundled references, records their hashes and CLI version, and skips identical installations. `skills status` distinguishes missing, current, outdated, legacy, unmanaged, modified and conflicting installations. The unmodified published 0.5.0 or 0.5.1 skill migrates automatically. Local changes are preserved by default. Only after choosing to replace those changes, run:
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
evolink skills install --agent codex --replace-modified --json
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Replacement backs up the previous skill directory under `~/.evolink-media/skill-backups/`, outside assistant discovery folders. Untracked user assets are preserved, and an installation failure rolls back completed directory swaps. Unowned skills, damaged manifests and symbolic-link destinations require resolving the conflict first. After upgrading the CLI, run `skills status` and `skills install` to synchronize its bundle; npm upgrades do not automatically update assistant skill folders.
|
|
68
|
+
|
|
69
|
+
For an idempotent installation prompt, check Node.js 22+ and `evolink --version` before installing; reuse a suitable installed CLI. In a released version supporting `setup`, use it with the current assistant's name. With older versions, retain the four separate setup steps above, reuse a working login, and explicitly verify balance, model discovery and assistant skill discovery. Installation authorization does not authorize a paid test generation.
|
|
70
|
+
|
|
45
71
|
## Quoted generation
|
|
46
72
|
|
|
47
73
|
```sh
|
|
@@ -58,6 +84,8 @@ For video/audio, choose the corresponding generation command and a model's docum
|
|
|
58
84
|
|
|
59
85
|
`--max-cost-usd` is an estimate-based submission guard, not a final-settlement guarantee. A complete estimate automatically uses its quoted maximum as this guard unless the user supplied a cap. Incomplete or unknown totals cannot use it. `--media-seconds` is a pricing hint, never a model parameter. Token-billed and unknown-duration models require explicit acceptance of their billing uncertainty; a missing price is refused.
|
|
60
86
|
|
|
87
|
+
A failed or blocked estimate is not a quote. Catalog starting prices must not replace a task quote. Fix the reported problem and quote again while retaining the user's cap; do not ask for generation approval or submit using an invented total. Quote errors report `submission_allowed: false` and preserve the supplied budget.
|
|
88
|
+
|
|
61
89
|
## Tasks and files
|
|
62
90
|
|
|
63
91
|
```sh
|
|
@@ -86,7 +114,39 @@ An invalid status is rejected locally before login or an MCP request. The `inval
|
|
|
86
114
|
|
|
87
115
|
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.
|
|
88
116
|
|
|
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.
|
|
117
|
+
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, check content types and common media file headers, stream at most 1 GiB per result, and refuse to overwrite existing files. HTTP 200 HTML/error documents are rejected with `invalid_download_content`, with no final file left behind. Header checks do not fully decode codecs. These commands transfer originals and do not alter the generated content or guarantee host inline previews. Missing files/directories, denied permissions and exhausted disk space have separate error codes; fix the local problem and retry the same task's download.
|
|
118
|
+
|
|
119
|
+
## Discovery, task pages and all-result delivery
|
|
120
|
+
|
|
121
|
+
Every command supports local `--help --json`, with option enums, bounds and defaults. New discovery tools and page/model/until filters require the updated MCP service. The CLI checks advertised capabilities and reports `capability_unavailable` before calling an unsupported tool or sending an unsupported filter.
|
|
122
|
+
|
|
123
|
+
```sh
|
|
124
|
+
evolink models recommend --type video --references image --query seedance --json
|
|
125
|
+
evolink models schema MODEL --json
|
|
126
|
+
evolink docs search --query voice_prompt --json
|
|
127
|
+
evolink models search --type video --page 2 --json
|
|
128
|
+
evolink tasks list --model MODEL --page 2 --limit 50 --json
|
|
129
|
+
evolink tasks batch --ids TASK_A,TASK_B --json
|
|
130
|
+
evolink download TASK_ID --all --output-dir /absolute/results --json
|
|
131
|
+
evolink download TASK_ID --all --output-dir /absolute/results --resume --json
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Recommendations report documented reference support and editorial selection reasons; they are not a quality, popularity or release-date ranking. Read the actual model inputs and prepare a quote before generating. Documentation search returns bundled official model-reference excerpts and a source commit, not a live full-site crawl. Schemas preserve nested OpenAPI definitions. `response_schema` describes submission rather than necessarily the final task result; runtime constraints remain authoritative.
|
|
135
|
+
|
|
136
|
+
Task pagination returns `page`, `page_size` and `next_page`. `since`/`until` filter only the selected page; `total` is before those time filters. Batch queries deduplicate known IDs and return missing IDs. Public voice/persona/result metadata is preserved in `outputs` without private upstream metadata.
|
|
137
|
+
|
|
138
|
+
All-result downloads accept up to 50 results. `--template '{task_id}-{index}.{ext}'` also supports `{kind}`; templates must produce distinct portable filenames without directories. Local receipts record sizes and SHA-256 hashes. `--resume` verifies saved files and downloads the remainder with the same task/directory/template. Changed files and unrelated existing files are preserved. Partial delivery returns successful files and per-result errors, exits nonzero, and leaves generation marked completed. Recover downloads using the original task; never regenerate to fix delivery.
|
|
139
|
+
|
|
140
|
+
## Usage and spending limits
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
evolink usage --since 30d --max-pages 5 --json
|
|
144
|
+
evolink usage --since 2026-10-01T00:00:00Z --until 2026-10-09T00:00:00Z --model MODEL --json
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
This account-wide summary scans at most 1–20 pages of 50 retained tasks (default 5), groups by task creation time, and sums valid reported costs of completed tasks. It includes coverage, scan bounds, missing costs and detected pagination changes. Missing costs are not zero. Complete coverage means currently retained matching tasks were scanned; historical completeness and a consistent snapshot remain unknown. It excludes reservations, payments, refunds and non-task charges and is not a bill or invoice. USD is approximate at 68 credits per dollar.
|
|
148
|
+
|
|
149
|
+
Final task/workflow budgets require authoritative server-side reservation and settlement. This version retains an estimate-based submission guard; task summaries or local waiting cannot enforce a final spending cap. No cancellation command or tool is provided.
|
|
90
150
|
|
|
91
151
|
## Authentication and state
|
|
92
152
|
|
|
@@ -94,6 +154,10 @@ Login uses a native public OAuth client, PKCE, a loopback callback and `mcp offl
|
|
|
94
154
|
|
|
95
155
|
Tokens are stored only in the OS credential store. Linux requires a running Secret Service keyring; the CLI does not silently fall back to an in-memory kernel store or plaintext credential files. A one-command OAuth access token can be passed through stdin with `--token-stdin`, never as a command argument. `auth logout` revokes this session and preserves the account's shared MCP key.
|
|
96
156
|
|
|
157
|
+
Run `evolink doctor --json` to check Node.js, writable local state, credential storage, saved login, balance connectivity and model discovery. Add `--agent NAME` to check installed skills. It reports failed and skipped checks together and exits nonzero until the connection is verified. On Linux, run login and later commands in the same unlocked Secret Service/D-Bus session. A keyring package alone does not start or unlock that session.
|
|
158
|
+
|
|
159
|
+
On an SSH host, the OAuth loopback callback belongs to the host running the CLI. If you open the link on your own computer, forward its callback port: run `evolink auth login --no-browser` remotely, read the `127.0.0.1:PORT` in the printed link's `redirect_uri`, then use a second local terminal with `ssh -N -L PORT:127.0.0.1:PORT USER@HOST` before opening that link. Keep both commands alive until approval finishes (the login waits up to three minutes). Otherwise run the CLI locally. `--no-browser` prints a link but does not forward it. Device-code login is not provided.
|
|
160
|
+
|
|
97
161
|
Quotes, request IDs and non-secret public client metadata retain the existing `~/.evolink-media` location so an upgrade can reuse saved requests and the OS-stored login. `EVOLINK_CLI_HOME` selects an isolated state directory; the original `EVOLINK_MEDIA_HOME` remains supported. The credential-service identity and skill ownership marker also remain stable across the command rename. Browser links are printed on stderr. Tokens and PKCE verifiers are not printed. Never include credentials in bug reports.
|
|
98
162
|
|
|
99
163
|
All machine-readable commands accept `--json`. Stdout contains one envelope with `schema_version: 1` and `ok`; progress goes to stderr. Errors return `ok: false`, an error code and a nonzero exit code (130 for interruption).
|
|
@@ -103,3 +167,21 @@ All machine-readable commands accept `--json`. Stdout contains one envelope with
|
|
|
103
167
|
Run installation and tests on the test cloud host, not the development Mac. In this package directory: `npm ci`, `npm test`, `npm run test:mutations`, and `npm pack`. Tests use loopback fixtures and never spend production credits. Real paid acceptance requires a separate quote and user approval.
|
|
104
168
|
|
|
105
169
|
Development starts in `deeplearning-goethe/evolink-cli`. After acceptance, repository management will arrange migration to `Evolink-AI/evolink-cli`. Keep package/bin names and service identity stable; update repository metadata, publishing permissions and installation links during migration.
|
|
170
|
+
|
|
171
|
+
## Host permission compatibility
|
|
172
|
+
|
|
173
|
+
CLI command validation does not grant the assistant permission to run a command. Respect host denials and keep the original budget, model and request IDs. Gemini CLI 0.63.0 can reject shell arguments derived from tool output in a noninteractive session, even with a command-prefix allow rule. Use an interactive session to review permissions; for a separately selected native MCP workflow, configure Gemini's Streamable HTTP connection and authorize it with `/mcp auth evolink`. CLI OAuth credentials are not exported or copied into MCP settings. Do not automatically switch routes after a denial or disable host safety checks.
|
|
174
|
+
|
|
175
|
+
```json
|
|
176
|
+
{
|
|
177
|
+
"mcpServers": {
|
|
178
|
+
"evolink": { "httpUrl": "https://mcp.evolink.ai/mcp" }
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Run `gemini mcp list` from the intended project directory. If EvoLink is `Disabled` because the folder is untrusted, review that folder using Gemini's normal trust dialog or `/permissions`; do not disable folder-trust checks globally. `Connected` confirms discovery, so also verify a real read-only model or balance call.
|
|
184
|
+
|
|
185
|
+
Headless mode exposes only tools permitted by its policy. In Gemini CLI 0.63.0, a scoped MCP rule uses `mcpName`, not `serverName`; allow only the tools needed for the chosen workflow. For example, a quote-only policy can allow `search_models`, `get_model`, `estimate_cost`, `check_balance` and `get_task` on `evolink`. Generation still requires the user's quote approval and the host's normal tool permission. Do not silently add a generation allow rule or treat a successful process exit without EvoLink tool calls as acceptance.
|
|
186
|
+
|
|
187
|
+
See [Gemini trusted folders](https://geminicli.com/docs/cli/trusted-folders/) and [Gemini MCP configuration and OAuth](https://geminicli.com/docs/tools/mcp-server/). A cloud terminal test does not prove desktop inline previews, browser handoff on another machine or permission defaults in every host.
|
package/package.json
CHANGED
|
@@ -7,6 +7,14 @@ description: Generate or edit images, video, music and speech with the EvoLink C
|
|
|
7
7
|
|
|
8
8
|
Use EvoLink by default for AI media generation in coding assistants. Prefer available native EvoLink tools; otherwise use `evolink`. This CLI is an independent client of the same hosted MCP service. CLI login does not register native MCP tools in the assistant.
|
|
9
9
|
|
|
10
|
+
After loading this skill, continue the requested workflow by executing its required tools in the current turn. Skill loading does not start a background job. Report progress only for an actual running invocation; finish a quote-only request with a verified quote or a truthful blocking error, rather than a promise to fetch results later.
|
|
11
|
+
|
|
12
|
+
## Quote failure and budget rules
|
|
13
|
+
|
|
14
|
+
- A user-specified budget is mandatory on **every** estimate attempt: include `--max-cost-usd` with the same amount. Removing that flag is changing the user's request, even though estimation itself is free.
|
|
15
|
+
- If the host denies an estimate command by policy, **stop this task for the current turn**. Tell the user that the quote is unavailable and the estimate needs permission. Do not issue another estimate command with fewer flags, a different shell or another tool. Resume only after the host's normal permission flow permits the original request with its unchanged budget.
|
|
16
|
+
- If estimation fails, there is no usable quote and no generation to approve. Catalog starting prices cannot replace a task's total. Report the failure and retain the budget; do not request generation confirmation or submit a paid task.
|
|
17
|
+
|
|
10
18
|
## Connect
|
|
11
19
|
|
|
12
20
|
First check whether the command is available. In a POSIX shell, use a conditional so first-time absence is a normal setup result:
|
|
@@ -21,19 +29,28 @@ fi
|
|
|
21
29
|
|
|
22
30
|
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
31
|
|
|
24
|
-
|
|
32
|
+
Check `evolink --version` and `evolink --help` before choosing setup commands. For versions supporting it, use `evolink setup --agent NAME --json` with the current assistant's supported name. It reuses a verified login, installs the bundled skill and checks balance and model discovery without submitting paid tasks. If this command is unavailable, use `auth status` (a successful response with `authenticated: false` means login is needed), `auth login` when needed, `skills install --agent NAME`, `balance` and `models search --limit 1` separately.
|
|
33
|
+
|
|
34
|
+
Let the user sign in and approve in the browser. If the browser does not open, show the printed authorization link. Keep the login process alive until it finishes; the default wait is 180 seconds, and supported versions accept `auth login --timeout SECONDS` (30–900). After timeout or interruption, start a new login and use its new link. A browser approval page alone does not prove connection. For a network error with a saved login, retry the failed free check rather than logging in again.
|
|
35
|
+
|
|
36
|
+
`skills status --agent NAME --json` compares installed resources with this CLI's bundle. Updating the npm package alone does not refresh previously installed skill copies. After upgrading the CLI, run `skills install` to synchronize them. On `skill_modified`, preserve the user's edits; use `--replace-modified` only when the user explicitly chooses replacement, which creates a backup. A written file or `assistant_discovery: not_checked` is not proof that the assistant loaded the skill. Confirm discovery in the current assistant; reopen the conversation only if it cannot refresh. Do not edit an installed skill copy as a substitute for fixing the package source.
|
|
25
37
|
|
|
26
|
-
|
|
38
|
+
If the assistant host denies a tool call, stop and explain the required permission. Keep the original budget and input; do not remove spending caps, rewrite the command to evade checks, or switch transports after a denial. Gemini CLI noninteractive sessions may block parameters discovered from tool output; use its interactive permission flow, or a separately configured native EvoLink MCP connection in a new session when the user chooses that route. For Gemini native MCP, check `gemini mcp list` in the intended workspace, review workspace trust through its normal permission flow, and verify a real read-only EvoLink call. Headless MCP permissions use scoped `mcpName` policy rules; do not silently grant generation permission or count an exit without tool calls as successful integration.
|
|
27
39
|
|
|
28
40
|
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.
|
|
29
41
|
|
|
30
42
|
## Prepare and quote
|
|
31
43
|
|
|
44
|
+
For image edits, reference-based video, speech or music, read [media workflows](references/media-workflows.md) when selecting inputs. Model discovery and `models show` determine actual support; never invent input fields or infer model quality from search order.
|
|
45
|
+
|
|
32
46
|
- Discover with `evolink models search --type image|video|audio --query "keywords" --json`; read supported parameters and prices with `models show MODEL --json`. Respect the user's chosen model and budget. Search order does not establish quality.
|
|
47
|
+
- When comparing reference support, retrieving schemas or searching model documentation, read [Discovery and delivery extensions](references/capabilities.md). Use `models recommend`, `models schema` and `docs search` only when the connected service supports them. Keep the user's chosen model; recommendations explain alternatives, not automatic approval.
|
|
33
48
|
- For a local reference, run `evolink upload /absolute/path --json` and use its `file_url` in the model input. A chat attachment must have a readable local file or public URL. Use `uploads get ID` after a lost upload result; do not run a second PUT to the same address.
|
|
34
49
|
- Prepare a JSON input file using the model's documented parameters. Run `evolink estimate --model MODEL --input-file /absolute/input.json --json`, adding `--max-cost-usd` only for a user-specified cap. `--media-seconds` is an estimation hint, not a model `duration` parameter or a billing guarantee.
|
|
35
50
|
- Show the user the model, input/reference, number/duration, output settings, estimated total and material uncertainties. For token billing or unknown duration, show the rates and state that the total is unknown. A partial estimate is not an upper bound. Spending caps currently protect the submission estimate, not final settlement.
|
|
36
51
|
|
|
52
|
+
Only a successful `estimate` response with `ok: true` and a returned `quote_id` can be approved. For invalid input, unavailable pricing, insufficient balance or an uncheckable cap, report the error and correct that problem before quoting again with the same budget. Do not invent a total or quote ID, run `generate --confirm`, or disable host permission controls.
|
|
53
|
+
|
|
37
54
|
Use a brief confirmation in the user's language, for example: “准备使用 {model},生成 {output},设置为 {settings}。预计费用 {cost}。确认按这个方案生成吗?” Include the relevant billing uncertainty when the total is unknown. Keep implementation details out of the product explanation unless the host requires them.
|
|
38
55
|
|
|
39
56
|
## Submit after approval
|
|
@@ -48,9 +65,16 @@ The saved model and input are the submitted model and input. A changed or expire
|
|
|
48
65
|
|
|
49
66
|
- 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
67
|
- `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
|
|
68
|
+
- 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 selected page, not the entire history. With the updated service, use `--page` and follow `next_page`; `--model` and `--until` narrow results. `total` is before time filtering. 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.
|
|
52
69
|
- 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.
|
|
53
70
|
- 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.
|
|
71
|
+
- For several original results, read [Discovery and delivery extensions](references/capabilities.md), then use `download TASK_ID --all --output-dir DIR --json`. Partial delivery is a command error even though generation completed. Resume only downloads with the same task/directory/template and `--resume`; verify saved files and never generate again to repair delivery.
|
|
72
|
+
- When the user asks for spending or usage, read [Usage and budget boundaries](references/usage-and-budget.md). Task summaries are not invoices or refund ledgers; missing costs and incomplete coverage must remain visible. An estimate guard is not a final settlement cap.
|
|
73
|
+
- If a download reports `invalid_download_content`, keep the existing task ID: the file service may have returned an error page. Retry only the download after resolving the error; do not generate a replacement task. For missing directories, permissions or a full disk, fix the reported local path before retrying.
|
|
54
74
|
- Downloading or compositing must not silently change the generated content. Further paid variations or regeneration require a new quote and approval.
|
|
55
75
|
|
|
76
|
+
Use `generate` for the first submission of an approved quote. `tasks resume` is only for a submission whose reply was lost or whose outcome is unknown; it is not a quote-status command. If it returns `submission_not_started`, no task exists: use the original already-approved quote with `generate`, without creating another quote.
|
|
77
|
+
|
|
56
78
|
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.
|
|
79
|
+
|
|
80
|
+
For setup problems, run `evolink doctor --agent NAME --json` if the installed version supports the agent option; otherwise use `doctor --json`. Read every failed or skipped check. On Linux, login and later commands need the same unlocked Secret Service/D-Bus session. On SSH hosts, opening the link on another computer requires forwarding the loopback callback port; `--no-browser` does not solve callback routing. Report connection, model discovery and assistant skill discovery separately.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Discovery and delivery extensions
|
|
2
|
+
|
|
3
|
+
Read only when comparing models, retrieving schemas, searching model references, querying known task batches or downloading several results.
|
|
4
|
+
|
|
5
|
+
Use `<command> --help --json` for a machine-readable command description, option enums, bounds and defaults. Help is local and needs no login. Discovery extensions and new list filters require the updated MCP service. `capability_unavailable` means the service does not advertise the tool or input field; report the required service update. Do not silently remove a requested filter.
|
|
6
|
+
|
|
7
|
+
## Model discovery
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
evolink models recommend --type video --references image --query seedance --json
|
|
11
|
+
evolink models schema MODEL --json
|
|
12
|
+
evolink docs search --query voice_prompt --type audio --json
|
|
13
|
+
evolink models search --type video --page 2 --limit 20 --json
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Recommendations filter currently available documented models by output type, search keywords and documented reference inputs. Explain the returned selection reasons. They do not establish quality, popularity or the newest release. Unit starting rates are not quotes; get the model parameters and estimate the actual task input before paid generation. Never drop a required reference kind to get a recommendation.
|
|
17
|
+
|
|
18
|
+
Model schemas are bundled official OpenAPI references with a source commit. `input_schema` retains nested schema definitions; additional runtime constraints in `constraints` and `schema_info` also apply. `response_schema` describes generation submission, which can be an asynchronous task receipt; it is not a promise that all final outputs appear in that schema. Unresolved references and unavailable schemas must be reported. Documentation search indexes model titles, IDs and parameter excerpts, not the whole live site or billing documentation.
|
|
19
|
+
|
|
20
|
+
## Batch recovery and resource results
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
evolink tasks batch --ids TASK_A,TASK_B --json
|
|
24
|
+
evolink tasks list --model MODEL --page 2 --limit 50 --json
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`tasks batch` deduplicates up to 50 task IDs and reports `missing`. Missing/foreign/expired IDs must not trigger automatic regeneration. Preserve `outputs` when a task returns a reusable `voice`, `voice_id`, `persona_id` or `result_id`. Verify the next model's actual input parameter before passing that resource onward. Returning an identifier does not establish a separate voice library, character training or resource-management product.
|
|
28
|
+
|
|
29
|
+
## All-result downloads
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
evolink download TASK_ID --all --output-dir /absolute/results --json
|
|
33
|
+
evolink download TASK_ID --all --output-dir /absolute/results --resume --json
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Optional `--template '{task_id}-{index}.{ext}'` supports `{task_id}`, `{index}`, `{kind}` and `{ext}`. Use a filename template, without directories or unknown placeholders. Filenames must be distinct. Individual transfers keep the existing DNS, content and size validation and never overwrite files.
|
|
37
|
+
|
|
38
|
+
The receipt records paths, sizes and SHA-256 digests in protected local CLI state. It contains no account credentials. Restore with the same task, service, directory and template. Saved files are checked again; modified files are reported and preserved. `ok: false`, nonzero exit and `delivery_status: partial` mean delivery is incomplete even if `generation_status: completed`. Report successful files and per-result failures; recover the remaining downloads without a paid submission. Downloads transfer originals and do not authorize post-processing.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Media workflows
|
|
2
|
+
|
|
3
|
+
Use these notes when the user requests an image edit, a reference-based video, speech or music. Follow the shared quote, approval, recovery and delivery workflow in SKILL.md for every task.
|
|
4
|
+
|
|
5
|
+
## Image creation and editing
|
|
6
|
+
|
|
7
|
+
- For a new image, discover image models and read the chosen model's parameters, supported dimensions and output count.
|
|
8
|
+
- For an edit, confirm that the source image is available as a readable local file or a public URL. Upload local files once, then pass the returned URL through the model's documented image-reference field.
|
|
9
|
+
- Describe the requested change and what should be preserved. Choose a model supporting those reference inputs; do not convert an edit into an unrelated text-to-image request.
|
|
10
|
+
|
|
11
|
+
## Video with reference media
|
|
12
|
+
|
|
13
|
+
- Identify whether the user needs text-to-video, an image as a first frame, multiple reference images or an existing video as input. Read the model's documented roles and limits before uploading or quoting.
|
|
14
|
+
- Keep duration, resolution, aspect ratio and sound explicit when supported. An input reference video's duration may affect billing independently of the requested output duration. Report partial estimates as partial totals.
|
|
15
|
+
- `--media-seconds` helps estimation only. It never establishes the model's duration parameter or a settlement ceiling.
|
|
16
|
+
|
|
17
|
+
## Speech and music
|
|
18
|
+
|
|
19
|
+
- For speech, distinguish text-to-speech from an edit of supplied audio. Choose only documented voice and language options. A voice name does not establish support for cloning or a reference voice.
|
|
20
|
+
- For music, establish instrumental versus vocals and the intended style. Only send lyrics, title, duration or other controls when the selected model supports them.
|
|
21
|
+
- Some audio models bill by input length or an output duration that is unknown in advance. Show the rates and that uncertainty before requesting approval; do not invent a total.
|
|
22
|
+
|
|
23
|
+
## Several outputs
|
|
24
|
+
|
|
25
|
+
Keep each quote bound to its exact inputs and budget. Approval must cover the concrete quoted outputs. Record each quote and task ID separately so a lost reply can be recovered without submitting duplicate tasks. If a task is already running, waiting or downloading its results does not authorize another generation.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Usage and budget boundaries
|
|
2
|
+
|
|
3
|
+
Read when the user asks about cost, historical usage, bills or spending limits.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
evolink balance --json
|
|
7
|
+
evolink usage --since 30d --max-pages 5 --json
|
|
8
|
+
evolink usage --since 2026-10-01T00:00:00Z --until 2026-10-09T00:00:00Z --model MODEL --json
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
`balance` reports the account balance and calling MCP key's reported limits. `usage` is an account-wide summary of retained generation tasks, grouped by task creation time. It scans at most `max-pages` × 50 tasks (default 5 pages, maximum 20), counts task states, and sums valid reported credits only for completed tasks. USD is approximate at 68 credits per dollar.
|
|
12
|
+
|
|
13
|
+
Always show the interval, account-wide scope, completed-task cost, missing-cost count and coverage. `complete_for_retained_tasks` means all currently retained matching tasks were scanned under the observed pagination; historical retention and snapshot consistency are not guaranteed. `truncated`, invalid rows or detected concurrent changes prevent claiming a full total. Do not turn missing costs into zero or infer a refund from failed/cancelled task status. This summary excludes reservations, payments, refunds and non-task charges. It is not a bill, tax invoice or a transactions API.
|
|
14
|
+
|
|
15
|
+
`--max-cost-usd` protects the submission estimate. It does not cap the final charge. Respect the user cap across retries and changed inputs; do not remove/increase it to get a successful response. Unknown totals, token usage, generated audio duration or incompletely priced reference inputs can make a cap uncheckable. Explain the returned uncertainty and await explicit acceptance of a change in scope or budget.
|
|
16
|
+
|
|
17
|
+
A final task/workflow cap requires server-side reservation and settlement enforcement with an authoritative quote and ledger. This client cannot create that guarantee by polling, summing history or stopping local waiting. Do not label this version as supporting final settlement budgets or downloadable invoices.
|
package/src/auth.mjs
CHANGED
|
@@ -73,15 +73,17 @@ export class OAuthProvider {
|
|
|
73
73
|
}
|
|
74
74
|
}
|
|
75
75
|
|
|
76
|
-
export function openBrowser(url) {
|
|
76
|
+
export function openBrowser(url, onFailure = () => {}) {
|
|
77
77
|
const command = process.platform === 'darwin' ? ['open', url] : process.platform === 'win32'
|
|
78
78
|
? ['rundll32.exe', 'url.dll,FileProtocolHandler', url] : ['xdg-open', url];
|
|
79
79
|
const child = spawn(command[0], command.slice(1), { stdio: 'ignore', detached: true, shell: false });
|
|
80
|
-
child.on('error',
|
|
80
|
+
child.on('error', onFailure);
|
|
81
|
+
child.on('exit', code => { if (code) onFailure(); });
|
|
81
82
|
child.unref();
|
|
82
83
|
}
|
|
83
84
|
|
|
84
85
|
export async function callbackListener({ state, issuer, timeout = 180_000, signal }) {
|
|
86
|
+
let settled = false;
|
|
85
87
|
let resolveCode, rejectCode;
|
|
86
88
|
const code = new Promise((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
|
|
87
89
|
// A timeout may happen before login reaches the await on this promise.
|
|
@@ -94,18 +96,25 @@ export async function callbackListener({ state, issuer, timeout = 180_000, signa
|
|
|
94
96
|
if (req.method !== 'GET' || url.pathname !== '/oauth/callback' || url.searchParams.get('state') !== state || url.searchParams.get('iss') !== issuer) {
|
|
95
97
|
res.writeHead(400); res.end('Invalid login callback. Return to the original browser login.'); return;
|
|
96
98
|
}
|
|
99
|
+
if (settled) { res.writeHead(410); res.end('This login callback has already finished. Return to your assistant or start a new login.'); return; }
|
|
97
100
|
if (url.searchParams.has('error')) {
|
|
98
101
|
res.writeHead(400); res.end('Login was not approved. You can close this window.');
|
|
102
|
+
settled = true;
|
|
99
103
|
rejectCode(new CliError('login_denied', 'Login was not approved.')); return;
|
|
100
104
|
}
|
|
101
105
|
const value = url.searchParams.get('code');
|
|
102
106
|
if (!value) { res.writeHead(400); res.end('Missing login code.'); return; }
|
|
103
|
-
|
|
107
|
+
settled = true;
|
|
108
|
+
const nonce = randomBytes(16).toString('base64url');
|
|
109
|
+
res.setHeader('Content-Type', 'text/html; charset=utf-8');
|
|
110
|
+
res.setHeader('Content-Security-Policy', `default-src 'none'; script-src 'nonce-${nonce}'; frame-ancestors 'none'; base-uri 'none'`);
|
|
111
|
+
res.writeHead(200);
|
|
112
|
+
res.end(`<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>EvoLink approval received</title><script nonce="${nonce}">history.replaceState(null, '', '/oauth/callback');</script><h1>EvoLink approval received</h1><p>Return to your assistant to finish checking the connection. You can close this window.</p><p>授权已收到。请返回助手完成连接检查,然后关闭此窗口。</p></html>`);
|
|
104
113
|
resolveCode(value);
|
|
105
114
|
});
|
|
106
115
|
await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
|
|
107
|
-
const timer = setTimeout(() => rejectCode(new CliError('login_timeout', 'Login timed out.
|
|
108
|
-
const abort = () => rejectCode(new CliError('interrupted', 'Login interrupted.',
|
|
116
|
+
const timer = setTimeout(() => { settled = true; rejectCode(new CliError('login_timeout', 'Login timed out. Start a new login and use its new browser link.', { recovery: 'evolink auth login', timeout_seconds: timeout / 1000 })); }, timeout);
|
|
117
|
+
const abort = () => { settled = true; rejectCode(new CliError('interrupted', 'Login interrupted. Start a new login when ready.', { recovery: 'evolink auth login' }, 130)); };
|
|
109
118
|
signal?.addEventListener('abort', abort, { once: true });
|
|
110
119
|
if (signal?.aborted) abort();
|
|
111
120
|
return { redirectUrl: `http://127.0.0.1:${server.address().port}/oauth/callback`, code,
|
|
@@ -138,27 +147,37 @@ export class Credentials {
|
|
|
138
147
|
return { access_token: saved.tokens.access_token, binding: saved.binding };
|
|
139
148
|
});
|
|
140
149
|
}
|
|
141
|
-
async login({ noBrowser = false, progress = () => {}, browser = openBrowser, signal } = {}) {
|
|
150
|
+
async login({ noBrowser = false, timeout = 180_000, progress = () => {}, browser = openBrowser, signal } = {}) {
|
|
142
151
|
requireThat(!this.token, 'invalid_option', 'auth login cannot use --token-stdin.');
|
|
152
|
+
requireThat(Number.isInteger(timeout) && timeout >= 30_000 && timeout <= 900_000, 'invalid_option', 'Login timeout must be between 30 and 900 seconds.');
|
|
143
153
|
return this.lock(async () => {
|
|
154
|
+
progress('Login: preparing browser authorization.');
|
|
144
155
|
await this.vault.read();
|
|
145
156
|
const provider = this.provider();
|
|
146
|
-
const listener = await callbackListener({ state: provider.oauthState, issuer: this.server.href === SERVER ? ISSUER : this.server.origin, signal });
|
|
157
|
+
const listener = await callbackListener({ state: provider.oauthState, issuer: this.server.href === SERVER ? ISSUER : this.server.origin, timeout, signal });
|
|
147
158
|
provider.redirectUrl = listener.redirectUrl;
|
|
148
159
|
provider.redirect = async url => {
|
|
149
160
|
// Validate the browser destination with the same origin policy as token requests.
|
|
150
161
|
const issuer = this.server.href === SERVER ? ISSUER : this.server.origin;
|
|
151
162
|
requireThat(url.origin === issuer, 'untrusted_auth_server', 'The browser login destination is outside EvoLink.');
|
|
152
163
|
progress(`Open this link to sign in and approve EvoLink:\n${url.href}`);
|
|
153
|
-
|
|
164
|
+
progress(`Login: waiting for browser approval (up to ${timeout / 1000} seconds). Keep this command running. Callback port: ${new URL(listener.redirectUrl).port}.`);
|
|
165
|
+
if (process.env.SSH_CONNECTION) progress('The callback belongs to this SSH host. Forward the callback port to your computer before opening the link. --no-browser does not forward it.');
|
|
166
|
+
if (!noBrowser) {
|
|
167
|
+
const failed = () => progress('The browser could not be opened automatically. Open the authorization link above while this command keeps running.');
|
|
168
|
+
try { await browser(url.href, failed); } catch { failed(); }
|
|
169
|
+
}
|
|
154
170
|
};
|
|
155
171
|
try {
|
|
156
172
|
let result = await auth(provider, { serverUrl: this.server, scope: 'mcp offline_access', fetchFn: this.fetchFn });
|
|
157
173
|
if (result === 'REDIRECT') {
|
|
158
174
|
provider.newLogin = true;
|
|
159
|
-
|
|
175
|
+
const authorizationCode = await listener.code;
|
|
176
|
+
progress('Login: browser approval received; completing secure login.');
|
|
177
|
+
result = await auth(provider, { serverUrl: this.server, scope: 'mcp offline_access', authorizationCode, fetchFn: this.fetchFn });
|
|
160
178
|
}
|
|
161
179
|
requireThat(result === 'AUTHORIZED', 'login_failed', 'Login could not finish.');
|
|
180
|
+
progress('Login: complete. Verify the connection with evolink balance --json.');
|
|
162
181
|
return { authenticated: true, server: this.server.href, credential_storage: 'os_keyring' };
|
|
163
182
|
} finally { await listener.close(); }
|
|
164
183
|
});
|