apipod-cli 0.1.0__py3-none-macosx_11_0_arm64.whl

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.
Binary file
@@ -0,0 +1,381 @@
1
+ Metadata-Version: 2.4
2
+ Name: apipod-cli
3
+ Version: 0.1.0
4
+ Summary: Generate images and video with APIPod from the terminal
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Keywords: apipod,cli,ai,image-generation,video-generation
8
+ Project-URL: Homepage, https://www.apipod.ai
9
+ Project-URL: Repository, https://github.com/geniuspath/apipod-cli
10
+ Project-URL: Issues, https://github.com/geniuspath/apipod-cli/issues
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Go
14
+ Classifier: Topic :: Multimedia :: Graphics
15
+ Classifier: Topic :: Multimedia :: Video
16
+ Requires-Python: >=3.8
17
+ Description-Content-Type: text/markdown
18
+
19
+ # apipod
20
+
21
+ [简体中文](README.zh-CN.md)
22
+
23
+ The command-line client for [APIPod](https://www.apipod.ai): generate images and
24
+ video, estimate what a generation costs, and upload reference media, from a
25
+ terminal, a script or an agent.
26
+
27
+ ```bash
28
+ apipod auth login
29
+ apipod image "a red fox in the snow" -m <model> --aspect 16:9 -o ./out
30
+ ```
31
+
32
+ Every command works for people (tables, progress on stderr) and for programs:
33
+ add `--json` for one JSON document on stdout, and branch on the
34
+ [exit code](#exit-codes).
35
+
36
+ ## Install
37
+
38
+ All channels install the same Go binary.
39
+
40
+ ```bash
41
+ brew install --cask geniuspath/tap/apipod
42
+ ```
43
+
44
+ ```bash
45
+ npm install -g apipod
46
+ ```
47
+
48
+ ```bash
49
+ pipx install apipod-cli
50
+ ```
51
+
52
+ Or download an archive from the
53
+ [releases page](https://github.com/geniuspath/apipod-cli/releases) and
54
+ [verify it](#verifying-a-download).
55
+
56
+ Notes:
57
+
58
+ - **npm** — the binary comes from a platform package
59
+ (`@apipod/cli-<os>-<cpu>`) installed through `optionalDependencies`. No
60
+ install script runs and nothing is downloaded at install time, so
61
+ `npm install --ignore-scripts` works.
62
+ - **pip** — the package is named `apipod-cli`. The name `apipod` on PyPI
63
+ belongs to an unrelated project that also installs a command called
64
+ `apipod`; use `pipx` or `uv tool install apipod-cli` so this CLI gets an
65
+ environment of its own.
66
+ - **Go** — `go install github.com/geniuspath/apipod-cli/cmd/apipod@latest`
67
+ (Go 1.24 or newer).
68
+
69
+ Shell completion: `apipod completion bash|zsh|fish|powershell` (the Homebrew
70
+ cask installs it for you).
71
+
72
+ ## Sign in
73
+
74
+ ```bash
75
+ apipod auth login
76
+ ```
77
+
78
+ This opens the browser, asks you to approve the "APIPod CLI" application, and
79
+ stores the resulting tokens in the system keychain. On a machine without a
80
+ browser, the sign-in URL is printed so you can open it elsewhere; the browser
81
+ must be able to reach `127.0.0.1` on the machine running the CLI.
82
+
83
+ To use an API key instead:
84
+
85
+ ```bash
86
+ export APIPOD_API_KEY=... # for scripts and CI
87
+ apipod auth login --with-api-key # stores a key in the keychain; reads stdin or a hidden prompt
88
+ ```
89
+
90
+ There is deliberately no `--api-key` flag: command-line arguments end up in
91
+ shell history and are visible to other processes.
92
+
93
+ ```bash
94
+ apipod auth status # which credential is in use (the secret is masked)
95
+ apipod auth logout # revokes the tokens, then removes them from this machine
96
+ ```
97
+
98
+ `APIPOD_API_KEY` takes precedence over a stored credential.
99
+
100
+ ## Examples
101
+
102
+ ```bash
103
+ # Find a model and see what it accepts
104
+ apipod models list --category video
105
+ apipod models params <model>
106
+
107
+ # What will it cost?
108
+ apipod cost <model> -d duration=10 -d resolution=1080p
109
+
110
+ # Generate an image, wait, and download it into ./out
111
+ apipod image "a red fox in the snow" -m <model> --aspect 16:9 -o ./out
112
+
113
+ # Edit a local image (it is uploaded first)
114
+ apipod image "make it night" -m <model> --image ./photo.png
115
+
116
+ # Video from a first frame, with model-specific parameters
117
+ apipod video "she turns and smiles" -m <model> --image ./frame.png \
118
+ --duration 5 --resolution 1080p -x generate_audio=true
119
+
120
+ # Submit without waiting, then pick the job up later
121
+ apipod video "a drone shot over a fjord" -m <model> --no-wait --json
122
+ apipod job wait <job-id> -o ./out
123
+
124
+ # Upload media and get URLs back
125
+ apipod upload ./photo.png ./clip.mp4 --json
126
+
127
+ apipod balance
128
+ ```
129
+
130
+ ### Model parameters
131
+
132
+ Parameters without a dedicated flag go in `-x key=value`. Names are lowercase
133
+ with underscores, exactly as `models params` prints them. A value that is
134
+ valid JSON is sent as JSON (`-x seed=42`, `-x draft=true`,
135
+ `-x camera='{"zoom":1.5}'`); anything else is sent as a string.
136
+ `-x key=@./file` uploads a local file and sends its URL. Dedicated flags win
137
+ over `-x`.
138
+
139
+ `--image`, `--video` and `--audio` fill `image_urls`, `video_urls` and
140
+ `audio_urls`. Some models name an input differently — `models params` shows
141
+ the exact name — and take it through `-x`:
142
+
143
+ ```bash
144
+ apipod video "extend the shot" -m <model> -x video_url=@./clip.mp4
145
+ ```
146
+
147
+ ### For scripts and agents
148
+
149
+ ```bash
150
+ job=$(apipod video "a sunrise" -m <model> --no-wait --max-cost 2 --json | jq -r .job_id)
151
+ apipod job wait "$job" -o ./out --json | jq -r '.results[].path'
152
+ ```
153
+
154
+ - `--json` prints exactly one JSON document on stdout. Progress and warnings go
155
+ to stderr. On failure stdout stays empty and stderr carries
156
+ `{"error": {"message", "exit_code", "code", "http_status", "job_id"}}`.
157
+ - `--max-cost <usd>` is a hard cap; `--yes` approves spending without a prompt.
158
+ Without a terminal one of the two is required above the confirmation
159
+ threshold (see [Spending guard](#spending-guard)).
160
+ - `--no-wait` returns the job id immediately; `--timeout` bounds a wait
161
+ (exit code 7, and the job keeps running).
162
+ - `--quiet` silences progress; `--no-color` disables colors (also `NO_COLOR`).
163
+
164
+ ## Commands
165
+
166
+ | Command | Purpose |
167
+ | --- | --- |
168
+ | `auth login` / `logout` / `status` | Sign in through the browser or store an API key; revoke; inspect |
169
+ | `models list [--category image\|video\|speech]` | Browse the catalog |
170
+ | `models params <model>` | Parameters a model accepts |
171
+ | `cost <model> [-d k=v] [--has-video]` | Price quote, with the current balance |
172
+ | `image <prompt> -m <model> [--image] [--aspect] [-n] [-x k=v]` | Generate or edit an image |
173
+ | `video [prompt] -m <model> [--image] [--video] [--audio] [--duration] [--resolution] [--aspect] [-x k=v]` | Generate a video |
174
+ | `job get <id>` / `job wait <id> [-o dir] [--timeout]` | Check a job; wait and download |
175
+ | `upload <file>...` | Upload local media, print public URLs |
176
+ | `balance [--open]` | Remaining balance; `--open` opens the billing page |
177
+ | `config get` / `set` / `list` | Local settings |
178
+ | `version`, `completion` | Version; shell completion scripts |
179
+
180
+ Global flags: `--json`, `--quiet`, `--no-color`, `--debug`, `--no-wait`,
181
+ `-o/--output <dir>`, `--max-cost <usd>`, `--yes`.
182
+
183
+ ### Exit codes
184
+
185
+ | Code | Meaning |
186
+ | --- | --- |
187
+ | 0 | Success |
188
+ | 1 | General error (including a job that failed) |
189
+ | 2 | Usage error |
190
+ | 3 | Authentication: not signed in, or the credential was rejected |
191
+ | 4 | Rate limited |
192
+ | 5 | Not found (model, job) |
193
+ | 6 | Billing: insufficient balance, over `--max-cost`, or spending not confirmed |
194
+ | 7 | Timeout |
195
+ | 8 | Validation: the request or a local file was rejected |
196
+
197
+ ### Configuration
198
+
199
+ Settings live in `config.toml` in the user configuration directory
200
+ (`apipod config list` prints the path). Credentials are never stored there.
201
+
202
+ | Key | Meaning |
203
+ | --- | --- |
204
+ | `defaults.image_model`, `defaults.video_model` | Model used when `-m` is omitted |
205
+ | `defaults.output` | `human` (default) or `json` |
206
+ | `spend.confirm_above` | Estimated cost in USD above which a generation needs approval (default `1`) |
207
+
208
+ | Environment variable | Meaning |
209
+ | --- | --- |
210
+ | `APIPOD_API_KEY` | API key; takes precedence over a stored credential |
211
+ | `APIPOD_BASE_URL` | API origin (default `https://api.apipod.ai`); must be `https`, except loopback |
212
+ | `APIPOD_CONSOLE_URL` | Web console origin, for self-hosted setups |
213
+ | `APIPOD_CONFIG_DIR` | Directory for `config.toml` and the fallback credential file |
214
+ | `NO_COLOR` | Disable colors |
215
+
216
+ ## Security
217
+
218
+ The CLI is meant to be safe to hand to an agent, including one that is being
219
+ fed hostile instructions. This section states what it does and does not do.
220
+
221
+ ### Credentials
222
+
223
+ - **Storage.** Tokens and keys go to the system keychain (macOS Keychain,
224
+ Windows Credential Manager, Secret Service on Linux). Only when no keychain
225
+ is available are they written to `credentials.json` with mode `0600`, with a
226
+ warning. That file is refused if group or others can access it, or if it is
227
+ a symbolic link.
228
+ - **No secrets in arguments.** No flag accepts a key or token. If one is typed
229
+ in the wrong place anyway — as a flag value, a command or a parameter name —
230
+ the usage error does not repeat it.
231
+ - **Bound to a host.** A credential is stored under the API origin that issued
232
+ it and is only ever sent there. Pointing `APIPOD_BASE_URL` at another host
233
+ does not send a stored credential to it. The API client does not follow
234
+ redirects.
235
+ - **HTTPS only.** A custom base URL must be `https`; plain `http` is accepted
236
+ for `127.0.0.1`, `::1` and `localhost` only.
237
+ - **Not printed.** `auth status` shows a masked value. With `--debug`,
238
+ `Authorization` and similar headers are replaced with `[REDACTED]`, known
239
+ secrets are removed from every logged line, and OAuth request bodies are not
240
+ logged at all.
241
+ - **An explicit environment key is yours to direct.** `APIPOD_API_KEY` is sent
242
+ to whatever `APIPOD_BASE_URL` names. If you override the base URL, you are
243
+ choosing where that key goes.
244
+
245
+ ### Sign-in
246
+
247
+ Authorization code flow with PKCE (S256) for the public client `apipod-cli`.
248
+ The callback listener binds `127.0.0.1` on a random port, accepts one callback,
249
+ compares `state` in constant time, times out after five minutes, and closes as
250
+ soon as the callback arrives. The callback page is static and echoes nothing
251
+ from the request. Access tokens last an hour and are renewed with a rotating
252
+ refresh token. `auth logout` revokes both tokens on the server and removes
253
+ them locally; if revocation fails, the local copy is still removed and you are
254
+ told to revoke the authorization in the console.
255
+
256
+ ### Spending guard
257
+
258
+ Before a generation the CLI asks the API for a price estimate.
259
+
260
+ - At or below `spend.confirm_above` (default $1): it proceeds.
261
+ - Above it, in a terminal: it asks.
262
+ - Above it, without a terminal: it **refuses with exit code 6** unless `--yes`
263
+ or `--max-cost` was given.
264
+ - `--max-cost <usd>` is a cap in every case, and `--yes` does not override it.
265
+ It must be a finite, non-negative number.
266
+ - If the price cannot be estimated, the request is treated as needing
267
+ approval; with `--max-cost` it is refused.
268
+
269
+ The check runs before any reference file is uploaded and before the task is
270
+ created.
271
+
272
+ The estimate is computed from the same parameters that are sent. Parameter
273
+ names given with `-x` and `-d` must be lowercase (`n`, not `N`): the API reads
274
+ request fields case-insensitively but prices them by exact name, so a
275
+ differently-cased name would be billed without being estimated. A reference
276
+ video is reported to the estimate whichever parameter carries it. A
277
+ `callback_url` is never forwarded; the CLI polls for the result.
278
+
279
+ The guard limits what one command can spend. It does not limit how many
280
+ commands are run: for a hard ceiling, give the agent an API key with a quota
281
+ set in the console.
282
+
283
+ Every generation request carries an `Idempotency-Key`, reused for each retry
284
+ of that request, so a retry is never billed as a second task. Only connection
285
+ errors and HTTP 429, 502 and 503 are retried.
286
+
287
+ ### Local files
288
+
289
+ - Only files named explicitly are read. Directories, symbolic links, devices
290
+ and FIFOs are refused; there is no globbing or recursion; at most 20 files
291
+ per command.
292
+ - The first 3 KB are sniffed and only PNG, JPEG, WebP, GIF, MP3, WAV, M4A, MP4,
293
+ WebM and MOV are accepted, whatever the extension. `apipod upload ~/.ssh/id_rsa`
294
+ or `apipod upload .env` is refused locally. Size limits match the server:
295
+ images 20 MB, audio 50 MB, video 100 MB.
296
+ - All files of a command are checked before anything is sent: one refused file
297
+ means no request is made.
298
+ - Only the file's base name is sent, not its path.
299
+ - **Uploaded files get public URLs.** Anyone who has the URL can open the file.
300
+ Do not upload anything you would not publish.
301
+
302
+ ### Downloads
303
+
304
+ Results are fetched with a separate HTTP client that never sends your
305
+ credential, over `https` only (redirects included). File names are generated by
306
+ the CLI as `<job-id>-<n>.<ext>`, with the extension taken from the content, so
307
+ the server cannot choose a path. Existing files are not overwritten without
308
+ `--force`. Files are written to a temporary name and renamed into place, with a
309
+ 2 GiB limit per file.
310
+
311
+ ### Terminal output
312
+
313
+ Text that comes from the server (model names, error messages, job fields) has
314
+ ANSI/OSC escape sequences, control characters and bidirectional overrides
315
+ removed before it is printed. `--json` output is escaped by the JSON encoder.
316
+
317
+ ### What the CLI does not do
318
+
319
+ It makes no payments (`balance --open` opens the console), accepts no password,
320
+ sends no telemetry, and does not check for updates.
321
+
322
+ ### Verifying a download
323
+
324
+ Release archives are listed in `checksums.txt`, which is signed with
325
+ [cosign](https://github.com/sigstore/cosign) using the release workflow's
326
+ identity. No signing key exists to be stolen.
327
+
328
+ ```bash
329
+ cosign verify-blob checksums.txt \
330
+ --bundle checksums.txt.sigstore.json \
331
+ --certificate-identity-regexp '^https://github\.com/geniuspath/apipod-cli/\.github/workflows/release\.yml@refs/tags/v' \
332
+ --certificate-oidc-issuer https://token.actions.githubusercontent.com
333
+ ```
334
+
335
+ ```bash
336
+ sha256sum --check --ignore-missing checksums.txt
337
+ ```
338
+
339
+ Each archive also has a GitHub build provenance attestation and an SPDX SBOM:
340
+
341
+ ```bash
342
+ gh attestation verify apipod_<version>_<os>_<arch>.tar.gz --repo geniuspath/apipod-cli
343
+ ```
344
+
345
+ npm packages are published with provenance (`npm audit signatures`), and PyPI
346
+ wheels through Trusted Publishing.
347
+
348
+ To report a vulnerability, see [SECURITY.md](SECURITY.md).
349
+
350
+ ## Development
351
+
352
+ ```bash
353
+ go test ./...
354
+ go vet ./...
355
+ go run ./cmd/apipod --help
356
+ ```
357
+
358
+ Against a local backend:
359
+
360
+ ```bash
361
+ APIPOD_BASE_URL=http://127.0.0.1:8080 go run ./cmd/apipod auth login
362
+ ```
363
+
364
+ Release dry run (needs [GoReleaser](https://goreleaser.com) v2.16 or newer):
365
+
366
+ ```bash
367
+ goreleaser check
368
+ ```
369
+
370
+ ```bash
371
+ goreleaser release --snapshot --clean --skip=sign,sbom
372
+ ```
373
+
374
+ Drop `--skip=sign,sbom` when `cosign` and `syft` are installed. Then
375
+ `node scripts/build-npm.mjs` and `python3 scripts/build_wheels.py` assemble the
376
+ npm packages and wheels from `dist/`; see [npm/README.md](npm/README.md) and
377
+ [python/README.md](python/README.md).
378
+
379
+ ## License
380
+
381
+ [MIT](LICENSE)
@@ -0,0 +1,5 @@
1
+ apipod_cli-0.1.0.data/scripts/apipod,sha256=Scd4U5BvFY8MQCmzqT2lioe0bYX27elZVqmexZiQ_aY,8260146
2
+ apipod_cli-0.1.0.dist-info/METADATA,sha256=Ly2Lhz53rMeRS0sSChW1ja2weP2z8t3q8teCz1AUcWo,14466
3
+ apipod_cli-0.1.0.dist-info/WHEEL,sha256=P65lDCnX-XAQjy2BNcuZJnjk9Aa_ELZfdXc9_GBW3ws,112
4
+ apipod_cli-0.1.0.dist-info/licenses/LICENSE,sha256=ruQR8GyTv1XQqwYYIcg56aRHB7WpFgmYfeE-TyAthHk,1067
5
+ apipod_cli-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: apipod-cli build_wheels.py
3
+ Root-Is-Purelib: false
4
+ Tag: py3-none-macosx_11_0_arm64
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 GeniusPath
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.