focalapi-cli 0.2.0 → 0.2.2
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/CHANGELOG.md +24 -10
- package/LICENSE +202 -202
- package/README.md +141 -155
- package/dist/cli.js +234 -50
- package/package.json +57 -53
- package/scripts/postinstall.cjs +41 -41
- package/skills/focalapi/SKILL.md +47 -54
- package/skills/focalapi-auth/SKILL.md +28 -30
- package/skills/focalapi-chat/SKILL.md +29 -32
- package/skills/focalapi-gen/SKILL.md +50 -53
- package/skills/focalapi-models/SKILL.md +55 -49
- package/skills/focalapi-task/SKILL.md +25 -25
- package/skills/focalapi-usage/SKILL.md +26 -27
package/README.md
CHANGED
|
@@ -1,155 +1,141 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# focalapi-cli
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
[](https://www.npmjs.com/package/focalapi-cli)
|
|
8
|
-
[](./LICENSE)
|
|
9
|
-
[](https://nodejs.org)
|
|
10
|
-
|
|
11
|
-
```shell
|
|
12
|
-
npm i -g focalapi-cli
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
</div>
|
|
16
|
-
|
|
17
|
-
focalapi-cli
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
#
|
|
51
|
-
focalapi
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
focalapi
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
focalapi
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
focalapi
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
-
|
|
103
|
-
-
|
|
104
|
-
-
|
|
105
|
-
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
npm run build
|
|
143
|
-
npm test
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
## 链接
|
|
147
|
-
|
|
148
|
-
- focalapi：<https://focalapi.com>
|
|
149
|
-
- Gitee：<https://gitee.com/xnn-ai/focalapi-cli>
|
|
150
|
-
- npm：<https://www.npmjs.com/package/focalapi-cli>
|
|
151
|
-
- 内置 Skills：[`./skills`](./skills)
|
|
152
|
-
|
|
153
|
-
## License
|
|
154
|
-
|
|
155
|
-
[Apache-2.0](./LICENSE)
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# focalapi-cli
|
|
4
|
+
|
|
5
|
+
**Give any AI Agent direct access to FocalAPI creative models**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/focalapi-cli)
|
|
8
|
+
[](./LICENSE)
|
|
9
|
+
[](https://nodejs.org)
|
|
10
|
+
|
|
11
|
+
```shell
|
|
12
|
+
npm i -g focalapi-cli
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
</div>
|
|
16
|
+
|
|
17
|
+
focalapi-cli turns FocalAPI's creative-model gateway into commands and Skills that an Agent can run directly. Users describe the outcome they want; the Agent does not need to probe models, guess parameters, handcraft requests, or switch platforms first.
|
|
18
|
+
|
|
19
|
+
It does not configure FocalAPI as the Agent's primary model or provider. Agents such as Codex, Claude Code, and Cursor keep their existing reasoning models and call FocalAPI only for creative tasks such as image and video generation.
|
|
20
|
+
|
|
21
|
+
## Connect in three steps
|
|
22
|
+
|
|
23
|
+
```shell
|
|
24
|
+
# 1. Install. Skills are synchronized automatically when lifecycle scripts are allowed.
|
|
25
|
+
npm i -g focalapi-cli
|
|
26
|
+
|
|
27
|
+
# 2. Configure a FocalAPI key.
|
|
28
|
+
focalapi auth login --key sk-xxxx
|
|
29
|
+
|
|
30
|
+
# 3. Connect every detected Agent, then verify the installation. The operation is idempotent.
|
|
31
|
+
focalapi connect
|
|
32
|
+
focalapi connect verify --json
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Create a key at <https://focalapi.com/console/token>. CI and sandbox environments can use `FOCALAPI_API_KEY`; self-hosted deployments can set `FOCALAPI_BASE_URL`.
|
|
36
|
+
|
|
37
|
+
If an npm security policy blocks lifecycle scripts, run `focalapi connect` explicitly. This is also the stable manual integration entry point. Set `FOCALAPI_SKIP_POSTINSTALL=1` to intentionally skip automatic post-install integration.
|
|
38
|
+
|
|
39
|
+
## Zero-guesswork Agent workflows
|
|
40
|
+
|
|
41
|
+
When no model is specified, the CLI reads the live model pool and detailed model contract available to the current key, selects the maintained FocalAPI default, and sends only one real generation request.
|
|
42
|
+
|
|
43
|
+
```shell
|
|
44
|
+
# Automatically select the current default image model.
|
|
45
|
+
focalapi gen image "Product hero image, soft studio lighting" -o ./out --json
|
|
46
|
+
|
|
47
|
+
# Automatically select the current default video model and return a task ID immediately.
|
|
48
|
+
focalapi gen video "Ocean waves hitting rocks, cinematic" --no-wait -o ./out --json
|
|
49
|
+
|
|
50
|
+
# Continue from next_command in the generation response without resubmitting the task.
|
|
51
|
+
focalapi task status <task-id> --json
|
|
52
|
+
focalapi task download <task-id> -o ./out --json
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
When the user specifies a model, read its authoritative contract first:
|
|
56
|
+
|
|
57
|
+
```shell
|
|
58
|
+
focalapi models get <model-id> --json
|
|
59
|
+
focalapi gen image "<prompt>" -m <model-id> [contract-supported options] -o ./out --json
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The CLI can also resolve a model without generating anything:
|
|
63
|
+
|
|
64
|
+
```shell
|
|
65
|
+
focalapi models resolve image --json
|
|
66
|
+
focalapi models resolve video --json
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`resolve` returns the exact `model.id`, verified `endpoint_type`, complete `supported_params`, candidate models, and a `next_command`. When a list summary and detailed contract disagree, the detailed contract is authoritative.
|
|
70
|
+
|
|
71
|
+
The maintained creative defaults are aligned with the current catalog: Seedream 5.0, GPT Image 2, Gemini 3.1 Image, Grok Imagine Image 2.0, Kling Image 3.0, Qwen Image 3.0, and Krea 2 for images; Seedance 2.5, Kling 3.0, Vidu Q3, Gemini Omni Flash, Grok Imagine Video 1.5, LTX 2.5, FLUX 3, and MiniMax H3 for video. Availability still depends on the current key, so runtime model details always take precedence over this overview.
|
|
72
|
+
|
|
73
|
+
## Agent integration
|
|
74
|
+
|
|
75
|
+
```shell
|
|
76
|
+
focalapi connect # Install or repair every detected Agent.
|
|
77
|
+
focalapi connect list # Inspect supported, detected, and installed targets.
|
|
78
|
+
focalapi connect install codex cursor # Install for selected Agents.
|
|
79
|
+
focalapi connect install --path <dir> # Install to an unlisted or project-level Skills directory.
|
|
80
|
+
focalapi connect verify --json # Verify Skill integrity and authentication readiness.
|
|
81
|
+
focalapi connect uninstall # Remove only managed Skills that the user has not modified.
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The built-in catalog currently covers 44 Agent targets, including Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, OpenClaw, Cline, Windsurf, Warp, Trae, Qwen Code, Kimi CLI, and Hermes. Targets such as Codex, Cline, Pi, and Warp that share `~/.agents/skills` are deduplicated by path, so the Skills are installed only once.
|
|
85
|
+
|
|
86
|
+
Installation is transactional: the current `focalapi-*` catalog is written as one unit, and any failed step rolls back the operation. The manifest records a SHA-256 directory digest for each Skill. By default, uninstall removes only managed Skills whose digest has not changed and preserves user-modified content.
|
|
87
|
+
|
|
88
|
+
The Skill routing contract requires Agents to:
|
|
89
|
+
|
|
90
|
+
- trigger FocalAPI for creative tasks even when the user does not name it;
|
|
91
|
+
- omit `--model` when no model is specified, letting the CLI select one without generating test samples;
|
|
92
|
+
- use only the live parameter contract returned by `models get` for an explicitly selected model;
|
|
93
|
+
- reuse the original `task_id` for asynchronous work instead of charging for duplicate submissions while a task is `pending`;
|
|
94
|
+
- return to the original task after resolving an authentication error rather than stopping at diagnostics.
|
|
95
|
+
|
|
96
|
+
## Current capability boundary
|
|
97
|
+
|
|
98
|
+
The fully validated automatic generation paths currently cover images and video, including image editing, reference-image creation, text-to-video, and image-to-video. The CLI retains text and audio commands, but an Agent may use them only when both the live model details and CLI help expose an executable contract. It never infers future audio, 3D, or other modality support from model names alone.
|
|
99
|
+
|
|
100
|
+
## Stable output for Agents
|
|
101
|
+
|
|
102
|
+
- All automation commands support `--json`; stdout contains JSON only, while progress and diagnostics go to stderr.
|
|
103
|
+
- Errors use `{ error: { code, message, hint, request_id? } }`.
|
|
104
|
+
- API keys are always redacted.
|
|
105
|
+
- Image results return local `files`; asynchronous video results return `task_id` and `next_command`.
|
|
106
|
+
- Local validation rejects known invalid billing multipliers and model parameters before sending a request.
|
|
107
|
+
|
|
108
|
+
## Command map
|
|
109
|
+
|
|
110
|
+
| Task | Command |
|
|
111
|
+
| --- | --- |
|
|
112
|
+
| Generate images with automatic or explicit model selection | `focalapi gen image` |
|
|
113
|
+
| Generate video with automatic or explicit model selection | `focalapi gen video` |
|
|
114
|
+
| Resolve models and inspect live contracts | `focalapi models resolve/get/search/list` |
|
|
115
|
+
| Check and download asynchronous tasks | `focalapi task status/download` |
|
|
116
|
+
| Sign in and inspect key status | `focalapi auth login/status/logout` |
|
|
117
|
+
| Inspect quota, usage, and diagnostics | `focalapi usage`, `focalapi doctor` |
|
|
118
|
+
| Connect Agent Skills | `focalapi connect` |
|
|
119
|
+
| Make read-only raw API requests | `focalapi request get/head` |
|
|
120
|
+
|
|
121
|
+
Every command includes built-in help: `focalapi <command> --help`.
|
|
122
|
+
|
|
123
|
+
## Development validation
|
|
124
|
+
|
|
125
|
+
```shell
|
|
126
|
+
npm install
|
|
127
|
+
npx tsc --noEmit
|
|
128
|
+
npm run build
|
|
129
|
+
npm test
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Links
|
|
133
|
+
|
|
134
|
+
- FocalAPI: <https://focalapi.com>
|
|
135
|
+
- GitHub: <https://github.com/focalapi/focalapi-cli>
|
|
136
|
+
- npm: <https://www.npmjs.com/package/focalapi-cli>
|
|
137
|
+
- Bundled Skills: [`./skills`](./skills)
|
|
138
|
+
|
|
139
|
+
## License
|
|
140
|
+
|
|
141
|
+
[Apache-2.0](./LICENSE)
|