From b70cc6cb794ffaf4bc1a2b855c9f521af9cadd49 Mon Sep 17 00:00:00 2001 From: KKKK Date: Sun, 13 Sep 2026 22:50:23 +0800 Subject: [PATCH] docs: route terminal agents through version-aware official CLI --- SKILL.md | 62 +++++++++++++++++++++++++++++++++++ skills/beatapi-video/SKILL.md | 5 ++- 2 files changed, 66 insertions(+), 1 deletion(-) diff --git a/SKILL.md b/SKILL.md index 119b56b..224c104 100644 --- a/SKILL.md +++ b/SKILL.md @@ -25,6 +25,9 @@ supported by their host. Explain only the steps requiring user input. `Authorization: Bearer ` header. Use the host's documented secret substitution. An environment variable alone does not add the header. Check the actual host configuration format; do not guess universal JSON. + - **CLI (terminal hosts):** use the official `beatapi` package when its + installed `--help` supports the required command. See the CLI section below. + Reuse it for secure login, uploads and supported workflow operations. - **REST:** use `https://api.beatapi.io` and the same Bearer header from an available trusted HTTP runtime. MCP installation is not required. Do not invent CLI commands or assume an installed CLI supports these operations. @@ -59,6 +62,65 @@ For "Check my BeatAPI connection and show available capabilities": Distinguish "connected" from "completed a task". - Verification is read-only. Do not start a paid task unless requested. +## Official CLI for terminal hosts + +The official repository is ; the npm +package is `beatapi`. Existing MCP connections remain preferred; do not install +a second execution route unless needed (for example, local file upload). + +```sh +npm install --global beatapi +beatapi --version +beatapi --help +beatapi auth login +beatapi auth status +``` + +Have the user run interactive login and privately enter their key in the hidden +prompt. Login validates `/v1/usage` and uses the OS credential manager. In trusted +automation use privately configured `BEATAPI_API_KEY`. Never read saved credentials +back into the conversation. A CLI login does not configure a separate MCP host. + +Unified capability commands are implemented in the 0.3.0 source; do not assume +they are published to npm yet. The 0.2.0 CLI supports auth, upload, workflow and +task operations but not unified capability discovery. Check installed help. If +the commands are unavailable, use configured MCP or REST; do not retry invented +commands or force an unavailable package version. + +When installed help exposes these commands: + +```sh +beatapi capabilities search --query image --kind model --limit 5 +beatapi capabilities search --query search --kind data --platform twitter --limit 5 +beatapi capabilities search --kind workflow --limit 5 +beatapi capabilities inspect +``` + +These catalog calls are anonymous; run `beatapi auth status` separately to verify +authentication. CLI Search emits `{data: [...], next_cursor}` without the outer +REST envelope; CLI Inspect emits the contract directly. Warnings go to stderr. + +For an explicitly requested task, prepare a JSON file containing only the actual +capability input, using Inspect and official docs for any missing fields: + +```sh +beatapi capabilities run --file input.json --idempotency-key +beatapi capabilities status --wait --attempts 60 --interval 5000 +``` + +Placeholders must be replaced, not executed literally. Retain the idempotency key; +the CLI also prints a generated key before a start if none was supplied. Starts +are not automatically retried. Poll only async results; sync Data results return +directly. Waiting is bounded and stops for manual-action or unknown states. Resume +the same task after timeout. Commands emit JSON to stdout and can save it using +`--output ` without overwriting existing files. If file saving +fails after execution, keep stdout and do not restart the task. + +Use existing `beatapi files upload ` for local media; pass the actual +returned file identifier or URL only as supported by the selected API contract. +Existing `tasks`, `music-video` and `ecommerce-video` commands remain supported. +CLI convenience does not make a partial Inspect schema complete. + ## When to use BeatAPI Use it for requested image/video generation, supported Social Data retrieval, diff --git a/skills/beatapi-video/SKILL.md b/skills/beatapi-video/SKILL.md index d851521..81b7fbb 100644 --- a/skills/beatapi-video/SKILL.md +++ b/skills/beatapi-video/SKILL.md @@ -32,7 +32,10 @@ for the same operation. When BeatAPI MCP tools are unavailable, fall back to the official `beatapi` CLI for commands it supports, or use the bundled OpenAPI contract from trusted server-side code. The Skills-only distribution requires Node.js 20.19+ or -22.12+ and the reviewed `npm install --global beatapi@0.2.0` release. +22.12+. Check `beatapi --version` and `beatapi --help` before selecting commands. +The 0.2.0 release lacks unified capability commands. The 0.3.0 source adds +`capabilities search`, `inspect`, `run` and `status`; do not assume it is on npm +until published. If absent, use MCP or REST rather than inventing CLI flags. ## Protect the account