nai-cli 0.1.0__tar.gz
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.
- nai_cli-0.1.0/.gitignore +7 -0
- nai_cli-0.1.0/CHANGELOG.md +5 -0
- nai_cli-0.1.0/LICENSE +21 -0
- nai_cli-0.1.0/PKG-INFO +105 -0
- nai_cli-0.1.0/README.md +68 -0
- nai_cli-0.1.0/README.zh.md +68 -0
- nai_cli-0.1.0/THIRD_PARTY_NOTICES.md +56 -0
- nai_cli-0.1.0/docs/architecture.md +144 -0
- nai_cli-0.1.0/docs/official-parity.md +175 -0
- nai_cli-0.1.0/docs/usage.md +363 -0
- nai_cli-0.1.0/pyproject.toml +93 -0
- nai_cli-0.1.0/skills/nai-cli/SKILL.md +85 -0
- nai_cli-0.1.0/skills/nai-cli/references/batch.md +15 -0
- nai_cli-0.1.0/skills/nai-cli/references/inpaint.md +33 -0
- nai_cli-0.1.0/skills/nai-cli/references/vibes.md +17 -0
- nai_cli-0.1.0/src/nai_cli/__init__.py +3 -0
- nai_cli-0.1.0/src/nai_cli/__main__.py +5 -0
- nai_cli-0.1.0/src/nai_cli/api.py +529 -0
- nai_cli-0.1.0/src/nai_cli/auth.py +240 -0
- nai_cli-0.1.0/src/nai_cli/batch.py +126 -0
- nai_cli-0.1.0/src/nai_cli/caches.py +56 -0
- nai_cli-0.1.0/src/nai_cli/charge.py +231 -0
- nai_cli-0.1.0/src/nai_cli/cli.py +110 -0
- nai_cli-0.1.0/src/nai_cli/comfyui.py +194 -0
- nai_cli-0.1.0/src/nai_cli/commands/__init__.py +61 -0
- nai_cli-0.1.0/src/nai_cli/commands/account.py +79 -0
- nai_cli-0.1.0/src/nai_cli/commands/batch.py +142 -0
- nai_cli-0.1.0/src/nai_cli/commands/config.py +57 -0
- nai_cli-0.1.0/src/nai_cli/commands/context.py +201 -0
- nai_cli-0.1.0/src/nai_cli/commands/copies.py +138 -0
- nai_cli-0.1.0/src/nai_cli/commands/cost.py +70 -0
- nai_cli-0.1.0/src/nai_cli/commands/generate.py +257 -0
- nai_cli-0.1.0/src/nai_cli/commands/generation.py +550 -0
- nai_cli-0.1.0/src/nai_cli/commands/grid.py +99 -0
- nai_cli-0.1.0/src/nai_cli/commands/image_tools.py +248 -0
- nai_cli-0.1.0/src/nai_cli/commands/interrogate.py +77 -0
- nai_cli-0.1.0/src/nai_cli/commands/lint.py +24 -0
- nai_cli-0.1.0/src/nai_cli/commands/local.py +62 -0
- nai_cli-0.1.0/src/nai_cli/commands/meta.py +102 -0
- nai_cli-0.1.0/src/nai_cli/commands/models.py +62 -0
- nai_cli-0.1.0/src/nai_cli/commands/output.py +165 -0
- nai_cli-0.1.0/src/nai_cli/commands/redact.py +48 -0
- nai_cli-0.1.0/src/nai_cli/commands/references.py +87 -0
- nai_cli-0.1.0/src/nai_cli/commands/spec.py +245 -0
- nai_cli-0.1.0/src/nai_cli/commands/stats.py +54 -0
- nai_cli-0.1.0/src/nai_cli/commands/strip.py +15 -0
- nai_cli-0.1.0/src/nai_cli/commands/tags.py +32 -0
- nai_cli-0.1.0/src/nai_cli/commands/texts.py +71 -0
- nai_cli-0.1.0/src/nai_cli/commands/vibe.py +151 -0
- nai_cli-0.1.0/src/nai_cli/commands/watermark.py +70 -0
- nai_cli-0.1.0/src/nai_cli/config.py +369 -0
- nai_cli-0.1.0/src/nai_cli/cost.py +114 -0
- nai_cli-0.1.0/src/nai_cli/data/random_prompt.json +2536 -0
- nai_cli-0.1.0/src/nai_cli/decode.py +87 -0
- nai_cli-0.1.0/src/nai_cli/enhance.py +137 -0
- nai_cli-0.1.0/src/nai_cli/errors.py +40 -0
- nai_cli-0.1.0/src/nai_cli/fs.py +209 -0
- nai_cli-0.1.0/src/nai_cli/grid.py +244 -0
- nai_cli-0.1.0/src/nai_cli/images.py +250 -0
- nai_cli-0.1.0/src/nai_cli/import_image.py +235 -0
- nai_cli-0.1.0/src/nai_cli/inpaint.py +476 -0
- nai_cli-0.1.0/src/nai_cli/ledger.py +146 -0
- nai_cli-0.1.0/src/nai_cli/lint.py +302 -0
- nai_cli-0.1.0/src/nai_cli/local_models.py +135 -0
- nai_cli-0.1.0/src/nai_cli/meta.py +606 -0
- nai_cli-0.1.0/src/nai_cli/models.py +308 -0
- nai_cli-0.1.0/src/nai_cli/naming.py +426 -0
- nai_cli-0.1.0/src/nai_cli/parser.py +611 -0
- nai_cli-0.1.0/src/nai_cli/pixel_snap.py +525 -0
- nai_cli-0.1.0/src/nai_cli/presets.py +276 -0
- nai_cli-0.1.0/src/nai_cli/prompt.py +457 -0
- nai_cli-0.1.0/src/nai_cli/random_prompt.py +285 -0
- nai_cli-0.1.0/src/nai_cli/request.py +621 -0
- nai_cli-0.1.0/src/nai_cli/rerun.py +177 -0
- nai_cli-0.1.0/src/nai_cli/resample.py +133 -0
- nai_cli-0.1.0/src/nai_cli/sam.py +63 -0
- nai_cli-0.1.0/src/nai_cli/share.py +392 -0
- nai_cli-0.1.0/src/nai_cli/sheet.py +86 -0
- nai_cli-0.1.0/src/nai_cli/tagger.py +464 -0
- nai_cli-0.1.0/src/nai_cli/tags.py +44 -0
- nai_cli-0.1.0/src/nai_cli/tidy.py +176 -0
- nai_cli-0.1.0/src/nai_cli/tokenizer.py +313 -0
- nai_cli-0.1.0/src/nai_cli/values.py +114 -0
- nai_cli-0.1.0/src/nai_cli/vibe.py +464 -0
- nai_cli-0.1.0/tests/conftest.py +68 -0
- nai_cli-0.1.0/tests/helpers.py +101 -0
- nai_cli-0.1.0/tests/samples.py +117 -0
- nai_cli-0.1.0/tests/test_accounts.py +469 -0
- nai_cli-0.1.0/tests/test_api.py +509 -0
- nai_cli-0.1.0/tests/test_architecture.py +351 -0
- nai_cli-0.1.0/tests/test_batch.py +456 -0
- nai_cli-0.1.0/tests/test_charge.py +360 -0
- nai_cli-0.1.0/tests/test_cli.py +124 -0
- nai_cli-0.1.0/tests/test_comfyui.py +138 -0
- nai_cli-0.1.0/tests/test_config.py +113 -0
- nai_cli-0.1.0/tests/test_enhance.py +129 -0
- nai_cli-0.1.0/tests/test_files.py +656 -0
- nai_cli-0.1.0/tests/test_generate.py +177 -0
- nai_cli-0.1.0/tests/test_grid.py +230 -0
- nai_cli-0.1.0/tests/test_import.py +432 -0
- nai_cli-0.1.0/tests/test_inpaint.py +362 -0
- nai_cli-0.1.0/tests/test_ledger.py +248 -0
- nai_cli-0.1.0/tests/test_local_models.py +400 -0
- nai_cli-0.1.0/tests/test_locks.py +77 -0
- nai_cli-0.1.0/tests/test_meta_lint.py +714 -0
- nai_cli-0.1.0/tests/test_naming.py +143 -0
- nai_cli-0.1.0/tests/test_pixel_snap.py +91 -0
- nai_cli-0.1.0/tests/test_prompt.py +173 -0
- nai_cli-0.1.0/tests/test_random_prompt.py +121 -0
- nai_cli-0.1.0/tests/test_request.py +358 -0
- nai_cli-0.1.0/tests/test_resample.py +70 -0
- nai_cli-0.1.0/tests/test_roundtrip.py +87 -0
- nai_cli-0.1.0/tests/test_share.py +304 -0
- nai_cli-0.1.0/tests/test_skill.py +47 -0
- nai_cli-0.1.0/tests/test_tags.py +126 -0
- nai_cli-0.1.0/tests/test_tokenizer.py +348 -0
- nai_cli-0.1.0/tests/test_v4.py +58 -0
- nai_cli-0.1.0/tests/test_vibe.py +722 -0
nai_cli-0.1.0/.gitignore
ADDED
nai_cli-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 nai-cli contributors
|
|
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.
|
nai_cli-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: nai-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Command-line client for NovelAI image generation
|
|
5
|
+
Project-URL: Homepage, https://github.com/obzawa/nai-cli
|
|
6
|
+
Project-URL: Repository, https://github.com/obzawa/nai-cli
|
|
7
|
+
Project-URL: Documentation, https://github.com/obzawa/nai-cli/blob/main/docs/usage.md
|
|
8
|
+
Project-URL: Changelog, https://github.com/obzawa/nai-cli/blob/main/CHANGELOG.md
|
|
9
|
+
Project-URL: Issues, https://github.com/obzawa/nai-cli/issues
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
License-File: THIRD_PARTY_NOTICES.md
|
|
13
|
+
Keywords: cli,image-generation,novelai
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Environment :: Console
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
24
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
25
|
+
Requires-Python: >=3.11
|
|
26
|
+
Requires-Dist: argon2-cffi>=23.1
|
|
27
|
+
Requires-Dist: httpx>=0.27
|
|
28
|
+
Requires-Dist: numpy>=1.26
|
|
29
|
+
Requires-Dist: pillow>=10.1
|
|
30
|
+
Requires-Dist: regex>=2024.11.6
|
|
31
|
+
Provides-Extra: dev
|
|
32
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
33
|
+
Requires-Dist: ruff>=0.8; extra == 'dev'
|
|
34
|
+
Provides-Extra: local
|
|
35
|
+
Requires-Dist: onnxruntime>=1.17; extra == 'local'
|
|
36
|
+
Description-Content-Type: text/markdown
|
|
37
|
+
|
|
38
|
+
# nai-cli
|
|
39
|
+
|
|
40
|
+
English | [中文](https://github.com/obzawa/nai-cli/blob/v0.1.0/README.zh.md)
|
|
41
|
+
|
|
42
|
+
nai-cli is an unofficial command-line client for [NovelAI](https://novelai.net) image generation. It covers text to image, image to image, inpainting, Enhance, upscaling, the Director tools and Vibes on V5, V4.5 and V4, and reads the settings stored in images so they can be generated again.
|
|
43
|
+
|
|
44
|
+
It builds requests by the same rules as the official web client, so the same settings and seed produce the same image; the [parity notes](https://github.com/obzawa/nai-cli/blob/v0.1.0/docs/official-parity.md#intentional-differences) list the exceptions. Every command prints JSON, one object or one line per job, which makes it easy to call from scripts and other programs.
|
|
45
|
+
|
|
46
|
+
Documentation: [usage guide](https://github.com/obzawa/nai-cli/blob/v0.1.0/docs/usage.md), [official client parity](https://github.com/obzawa/nai-cli/blob/v0.1.0/docs/official-parity.md), [compatibility](https://github.com/obzawa/nai-cli/blob/v0.1.0/docs/usage.md#compatibility)
|
|
47
|
+
|
|
48
|
+
## Install
|
|
49
|
+
|
|
50
|
+
Python 3.11 or later is required:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
pipx install nai-cli
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
This installs the `nai` command in an environment of its own. `uv tool install nai-cli` and `pip install nai-cli` work as well. Reading tags from images and masking objects run on your computer and need `pipx install "nai-cli[local]"`.
|
|
57
|
+
|
|
58
|
+
## Configure
|
|
59
|
+
|
|
60
|
+
Create a persistent API token in NovelAI under Account Settings (it starts with `pst-`), then create a config file:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
nai config init
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The command prints the path of the new file. Put the token in its `novelai_token` field, or set the `NOVELAI_TOKEN` environment variable instead. Once the token works, `nai account` shows your balance.
|
|
67
|
+
|
|
68
|
+
## Usage
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
nai gen --prompt "1girl, rooftop, night" --dry-run
|
|
72
|
+
nai gen --prompt @prompt.txt --size landscape
|
|
73
|
+
nai inpaint --image a.png --region ellipse:0.62,0.40,0.80,0.58 --prompt "1girl, rooftop, night, open hand" --preview
|
|
74
|
+
nai enhance --image a.png
|
|
75
|
+
nai meta a.png
|
|
76
|
+
nai batch jobs.jsonl --dry-run
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`--dry-run` builds and prices the request without sending anything paid. The `prompt` and `negative` fields of the output hold the final text, including the quality tags and UC preset added automatically; without `--dry-run`, the saved files are listed in `images`. `@prompt.txt` reads the prompt from a file. `inpaint` repaints an area given in fractions of the image and composites the result back onto it, and `--preview` saves an image marking that area before anything is sent. `enhance` upscales and refines an image with the settings stored in it, and `meta` reads those settings so that `nai gen` can reproduce the image. `batch` runs a list of commands, one per line, and prints a JSON line for each, so other programs can queue work and resume it after a failure.
|
|
80
|
+
|
|
81
|
+
`nai --help` lists all commands, and `nai COMMAND --help` shows their options. The [usage guide](https://github.com/obzawa/nai-cli/blob/v0.1.0/docs/usage.md) covers each command, the output format and the error codes.
|
|
82
|
+
|
|
83
|
+
## Agent skill
|
|
84
|
+
|
|
85
|
+
nai-cli includes a skill in the [Agent Skills](https://agentskills.io) format that teaches AI agents to use it: dry-running before spending Anlas, asking before exceeding the spending limit, recovering from errors and repainting part of an image. Install it with:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
npx skills add obzawa/nai-cli
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
This installs it for the current project; add `-g` to install it for all projects. The skill itself is in [skills/nai-cli](https://github.com/obzawa/nai-cli/blob/v0.1.0/skills/nai-cli).
|
|
92
|
+
|
|
93
|
+
## Development
|
|
94
|
+
|
|
95
|
+
See [CONTRIBUTING.md](https://github.com/obzawa/nai-cli/blob/v0.1.0/CONTRIBUTING.md) for setting up, the checks a change must pass and how to report bugs; coding agents follow [AGENTS.md](https://github.com/obzawa/nai-cli/blob/v0.1.0/AGENTS.md).
|
|
96
|
+
|
|
97
|
+
## Acknowledgements
|
|
98
|
+
|
|
99
|
+
Thanks to [NovelAI](https://novelai.net) for the models and the service. Many of the defaults and conveniences follow [NAI Launcher](https://github.com/Aaalice233/Aaalice_NAI_Launcher), and image resizing is ported from [Pica](https://github.com/nodeca/pica).
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
[MIT](https://github.com/obzawa/nai-cli/blob/v0.1.0/LICENSE)
|
|
104
|
+
|
|
105
|
+
Third-party code and its licenses are listed in [THIRD_PARTY_NOTICES.md](https://github.com/obzawa/nai-cli/blob/v0.1.0/THIRD_PARTY_NOTICES.md).
|
nai_cli-0.1.0/README.md
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# nai-cli
|
|
2
|
+
|
|
3
|
+
English | [中文](README.zh.md)
|
|
4
|
+
|
|
5
|
+
nai-cli is an unofficial command-line client for [NovelAI](https://novelai.net) image generation. It covers text to image, image to image, inpainting, Enhance, upscaling, the Director tools and Vibes on V5, V4.5 and V4, and reads the settings stored in images so they can be generated again.
|
|
6
|
+
|
|
7
|
+
It builds requests by the same rules as the official web client, so the same settings and seed produce the same image; the [parity notes](docs/official-parity.md#intentional-differences) list the exceptions. Every command prints JSON, one object or one line per job, which makes it easy to call from scripts and other programs.
|
|
8
|
+
|
|
9
|
+
Documentation: [usage guide](docs/usage.md), [official client parity](docs/official-parity.md), [compatibility](docs/usage.md#compatibility)
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
Python 3.11 or later is required:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
pipx install nai-cli
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
This installs the `nai` command in an environment of its own. `uv tool install nai-cli` and `pip install nai-cli` work as well. Reading tags from images and masking objects run on your computer and need `pipx install "nai-cli[local]"`.
|
|
20
|
+
|
|
21
|
+
## Configure
|
|
22
|
+
|
|
23
|
+
Create a persistent API token in NovelAI under Account Settings (it starts with `pst-`), then create a config file:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
nai config init
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The command prints the path of the new file. Put the token in its `novelai_token` field, or set the `NOVELAI_TOKEN` environment variable instead. Once the token works, `nai account` shows your balance.
|
|
30
|
+
|
|
31
|
+
## Usage
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
nai gen --prompt "1girl, rooftop, night" --dry-run
|
|
35
|
+
nai gen --prompt @prompt.txt --size landscape
|
|
36
|
+
nai inpaint --image a.png --region ellipse:0.62,0.40,0.80,0.58 --prompt "1girl, rooftop, night, open hand" --preview
|
|
37
|
+
nai enhance --image a.png
|
|
38
|
+
nai meta a.png
|
|
39
|
+
nai batch jobs.jsonl --dry-run
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`--dry-run` builds and prices the request without sending anything paid. The `prompt` and `negative` fields of the output hold the final text, including the quality tags and UC preset added automatically; without `--dry-run`, the saved files are listed in `images`. `@prompt.txt` reads the prompt from a file. `inpaint` repaints an area given in fractions of the image and composites the result back onto it, and `--preview` saves an image marking that area before anything is sent. `enhance` upscales and refines an image with the settings stored in it, and `meta` reads those settings so that `nai gen` can reproduce the image. `batch` runs a list of commands, one per line, and prints a JSON line for each, so other programs can queue work and resume it after a failure.
|
|
43
|
+
|
|
44
|
+
`nai --help` lists all commands, and `nai COMMAND --help` shows their options. The [usage guide](docs/usage.md) covers each command, the output format and the error codes.
|
|
45
|
+
|
|
46
|
+
## Agent skill
|
|
47
|
+
|
|
48
|
+
nai-cli includes a skill in the [Agent Skills](https://agentskills.io) format that teaches AI agents to use it: dry-running before spending Anlas, asking before exceeding the spending limit, recovering from errors and repainting part of an image. Install it with:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
npx skills add obzawa/nai-cli
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
This installs it for the current project; add `-g` to install it for all projects. The skill itself is in [skills/nai-cli](skills/nai-cli).
|
|
55
|
+
|
|
56
|
+
## Development
|
|
57
|
+
|
|
58
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for setting up, the checks a change must pass and how to report bugs; coding agents follow [AGENTS.md](AGENTS.md).
|
|
59
|
+
|
|
60
|
+
## Acknowledgements
|
|
61
|
+
|
|
62
|
+
Thanks to [NovelAI](https://novelai.net) for the models and the service. Many of the defaults and conveniences follow [NAI Launcher](https://github.com/Aaalice233/Aaalice_NAI_Launcher), and image resizing is ported from [Pica](https://github.com/nodeca/pica).
|
|
63
|
+
|
|
64
|
+
## License
|
|
65
|
+
|
|
66
|
+
[MIT](LICENSE)
|
|
67
|
+
|
|
68
|
+
Third-party code and its licenses are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# nai-cli
|
|
2
|
+
|
|
3
|
+
[English](README.md) | 中文
|
|
4
|
+
|
|
5
|
+
nai-cli 是 [NovelAI](https://novelai.net) 图像生成的非官方命令行客户端,支持 V5、V4.5 与 V4 的文生图、图生图、局部重绘、Enhance、放大、导演工具与 Vibe,并能读出图片中保存的参数以重新生成。
|
|
6
|
+
|
|
7
|
+
它按官网前端的规则组装请求,相同的参数与种子会生成与官网相同的图像,例外见[规则对照](docs/official-parity.md#intentional-differences)。每条命令输出 JSON(一个对象,或每个任务一行),便于在脚本和其他程序中调用。
|
|
8
|
+
|
|
9
|
+
文档(英文):[使用说明](docs/usage.md)、[官网规则对照](docs/official-parity.md)、[兼容性](docs/usage.md#compatibility)
|
|
10
|
+
|
|
11
|
+
## 安装
|
|
12
|
+
|
|
13
|
+
需要 Python 3.11 或更高版本:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
pipx install nai-cli
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
该命令会把 `nai` 安装在独立的环境中,也可以改用 `uv tool install nai-cli` 或 `pip install nai-cli`。反推标签和按物体抠蒙版在本机运行,需要安装 `pipx install "nai-cli[local]"`。
|
|
20
|
+
|
|
21
|
+
## 配置
|
|
22
|
+
|
|
23
|
+
在 NovelAI 的账号设置中生成持久 API 令牌(以 `pst-` 开头),然后创建配置文件:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
nai config init
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
该命令会输出新配置文件的路径。将令牌填入其中的 `novelai_token`,或改为设置环境变量 `NOVELAI_TOKEN`。令牌生效后,`nai account` 会显示账户余额。
|
|
30
|
+
|
|
31
|
+
## 使用
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
nai gen --prompt "1girl, rooftop, night" --dry-run
|
|
35
|
+
nai gen --prompt @prompt.txt --size landscape
|
|
36
|
+
nai inpaint --image a.png --region ellipse:0.62,0.40,0.80,0.58 --prompt "1girl, rooftop, night, open hand" --preview
|
|
37
|
+
nai enhance --image a.png
|
|
38
|
+
nai meta a.png
|
|
39
|
+
nai batch jobs.jsonl --dry-run
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`--dry-run` 只组装请求并估价,不发送付费请求。输出中的 `prompt` 与 `negative` 是最终发送的文本,包含自动添加的质量词和 UC 预设;去掉 `--dry-run` 即正式生成,保存的文件列在 `images` 中。`@prompt.txt` 表示从文件读取提示词。`inpaint` 按图像比例坐标重绘指定区域并贴回原图,`--preview` 会在发送前保存一张标出该区域的预览图。`enhance` 按图像中保存的参数放大精修,`meta` 读取这些参数,供 `nai gen` 复现该图像。`batch` 按行执行一组命令,每条输出一行 JSON,便于其他程序排队提交,失败后接着跑剩下的。
|
|
43
|
+
|
|
44
|
+
`nai --help` 列出全部命令,`nai <命令> --help` 显示各命令的参数。各命令、输出格式与错误码详见[使用说明](docs/usage.md)。
|
|
45
|
+
|
|
46
|
+
## Agent 技能
|
|
47
|
+
|
|
48
|
+
nai-cli 附带一个 [Agent Skills](https://agentskills.io) 格式的技能,指导 AI agent 使用本工具:消耗 Anlas 前先试运行、超出单次花费上限前先征得同意、处理错误,以及局部重绘的操作流程。安装方式:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
npx skills add obzawa/nai-cli
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
默认安装到当前项目,加 `-g` 则对所有项目生效。技能文件位于 [skills/nai-cli](skills/nai-cli)。
|
|
55
|
+
|
|
56
|
+
## 开发
|
|
57
|
+
|
|
58
|
+
环境搭建、提交改动前要通过的检查和报告问题的方式见 [CONTRIBUTING.md](CONTRIBUTING.md);编程 agent 遵循 [AGENTS.md](AGENTS.md)。
|
|
59
|
+
|
|
60
|
+
## 致谢
|
|
61
|
+
|
|
62
|
+
感谢 [NovelAI](https://novelai.net) 提供模型与服务。许多默认参数与便利功能参考了 [NAI Launcher](https://github.com/Aaalice233/Aaalice_NAI_Launcher),图像缩放移植自 [Pica](https://github.com/nodeca/pica)。
|
|
63
|
+
|
|
64
|
+
## 许可证
|
|
65
|
+
|
|
66
|
+
[MIT](LICENSE)
|
|
67
|
+
|
|
68
|
+
第三方代码及其许可证见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Third-Party Notices
|
|
2
|
+
|
|
3
|
+
nai-cli is licensed under [MIT](LICENSE). It contains code derived from the projects listed below. Each project remains under its own license; nothing in this file changes those terms.
|
|
4
|
+
|
|
5
|
+
| Project | Used in | License |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| [Pica](https://github.com/nodeca/pica) | Lanczos3 resizing in `src/nai_cli/resample.py` | MIT |
|
|
8
|
+
| [NAI Launcher](https://github.com/Aaalice233/Aaalice_NAI_Launcher) | Prompt formatting rules in `src/nai_cli/tidy.py`, the protected kaomoji list in `src/nai_cli/prompt.py` and numeric weight checks in `src/nai_cli/prompt.py`, `src/nai_cli/tidy.py` and `src/nai_cli/lint.py`; ComfyUI multi-character parsing in `src/nai_cli/comfyui.py`; the corrected random prompt recipe in `src/nai_cli/random_prompt.py`; watermark placement and toning and the redaction effects in `src/nai_cli/share.py`; tagger preprocessing and tag list formats in `src/nai_cli/tagger.py`; SAM pre- and post-processing in `src/nai_cli/sam.py`; folder rules in `src/nai_cli/naming.py`; where copies are saved and how they keep settings in `src/nai_cli/commands/copies.py` | MIT |
|
|
9
|
+
|
|
10
|
+
## Pica
|
|
11
|
+
|
|
12
|
+
The MIT License
|
|
13
|
+
|
|
14
|
+
Copyright (C) 2014-2017 by Vitaly Puzrin
|
|
15
|
+
|
|
16
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
17
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
18
|
+
in the Software without restriction, including without limitation the rights
|
|
19
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
20
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
21
|
+
furnished to do so, subject to the following conditions:
|
|
22
|
+
|
|
23
|
+
The above copyright notice and this permission notice shall be included in
|
|
24
|
+
all copies or substantial portions of the Software.
|
|
25
|
+
|
|
26
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
27
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
28
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
29
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
30
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
31
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
32
|
+
THE SOFTWARE.
|
|
33
|
+
|
|
34
|
+
## NAI Launcher
|
|
35
|
+
|
|
36
|
+
MIT License
|
|
37
|
+
|
|
38
|
+
Copyright (c) 2026 NAI Launcher Contributors
|
|
39
|
+
|
|
40
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
41
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
42
|
+
in the Software without restriction, including without limitation the rights
|
|
43
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
44
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
45
|
+
furnished to do so, subject to the following conditions:
|
|
46
|
+
|
|
47
|
+
The above copyright notice and this permission notice shall be included in all
|
|
48
|
+
copies or substantial portions of the Software.
|
|
49
|
+
|
|
50
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
51
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
52
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
53
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
54
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
55
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
56
|
+
SOFTWARE.
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
nai-cli is one core and a thin front end. The core knows NovelAI: how requests are built, what images carry, what things cost. The front end knows the command line: options, standard input, JSON on standard output and exit codes. Commands sit between them and decide what happens in which order. A Python API or another front end later reuses the commands unchanged.
|
|
4
|
+
|
|
5
|
+
## Layers
|
|
6
|
+
|
|
7
|
+
Each layer imports only from the layers below it. `tests/test_architecture.py` enforces the order, the core's limits below and the rule that only `fs.py` writes files.
|
|
8
|
+
|
|
9
|
+
| Layer | Modules | Knows about |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| Front end | `cli.py`, `parser.py`, `__main__.py` | argv, standard input, JSON output, exit codes |
|
|
12
|
+
| Commands | `commands/*.py` | the steps of one command: read inputs, check prices and budget, call the core, save, report |
|
|
13
|
+
| Orchestration | `charge.py`, `batch.py`, `grid.py`, `import_image.py`, `caches.py` | paid-request lifecycle, resumable job runs and grids of them, the official import assignment chain, the tokenizer files and Vibe encodings kept between runs |
|
|
14
|
+
| Core | `request.py`, `prompt.py`, `tidy.py`, `models.py`, `presets.py`, `meta.py`, `rerun.py`, `vibe.py`, `inpaint.py`, `enhance.py`, `cost.py`, `naming.py`, `tokenizer.py`, `lint.py`, `tags.py`, `resample.py`, `images.py`, `share.py`, `random_prompt.py`, `sheet.py`, `pixel_snap.py`, `comfyui.py`, `tagger.py`, `sam.py` | NovelAI rules as plain functions over plain data |
|
|
15
|
+
| I/O | `api.py`, `auth.py`, `fs.py`, `ledger.py`, `config.py`, `local_models.py`, `decode.py`, `values.py`, `errors.py` | network, accounts and logins, disk, the spend ledger, the config file, local model files, reading image bytes, values as files and options give them, error codes |
|
|
16
|
+
|
|
17
|
+
The core never reads argv, prints, or decides where files go. It reads the files it is given and the data shipped inside the package, but never looks for files, talks to the network, loads models, reads the config, the data folder or the ledger, or writes; of the I/O layer it imports only `errors`, `values` and `decode`. Whatever it needs from outside, such as a tokenizer or a local model, is loaded above it and passed in. A function that needs a decision from the user takes it as an argument.
|
|
18
|
+
|
|
19
|
+
### Front end
|
|
20
|
+
|
|
21
|
+
`parser.py` declares every option and nothing else: name, type, default, help. The same declarations feed `--help`, docs/usage.md checks and the skill check, so an option exists in one place.
|
|
22
|
+
|
|
23
|
+
`cli.py` turns argv into options, options into settings, runs the command and prints its result. Nothing else.
|
|
24
|
+
|
|
25
|
+
### From argv to settings
|
|
26
|
+
|
|
27
|
+
Arguments go through two stages, and commands only ever see the second.
|
|
28
|
+
|
|
29
|
+
1. **Options**: what was typed, as parsed by `parser.py`. Unset options are `None`, so "not given" and "given as false or empty" stay different; every on/off option has a `--no-` form.
|
|
30
|
+
2. **Settings**: one immutable dataclass per command, resolved once. Resolution reads `@FILE` and `@-` for the options typed on the command line, merges the config file, imports from an image, picks the model and applies its limits. Precedence is fixed: command line, then imported image settings where the command imports them, then the config file, then built-in defaults.
|
|
31
|
+
|
|
32
|
+
Commands never read the config file, never look at options and never store state on them. Text that comes from an image or a job file is data; it never passes through `@` resolution.
|
|
33
|
+
|
|
34
|
+
### Context
|
|
35
|
+
|
|
36
|
+
A command gets its outside world from one context object: the config, loaded once, a client created when first needed, the clock, standard input, the argv for the ledger and whether this is a dry run. The front end builds it once per run. Each `batch` job gets a child context that shares the config, so the batch's limits hold, has its own client and refuses standard input; a job may name its own `--account`, and `--config` in a job is refused. The shared part also keeps the spacing of requests between jobs, how jobs are parsed, and the balance a dry run of several jobs reads once per account. `config init` clears the loaded config so later jobs read the new file. A dry run never renews a login: its balance reads use the stored token as it is.
|
|
37
|
+
|
|
38
|
+
### Commands
|
|
39
|
+
|
|
40
|
+
One file per command family under `commands/`: generation (`gen`, `enhance`, `variations`, `inpaint`), `tool`, `upscale`, `vibe`, `meta`, `grid`, `strip`, `redact`, `watermark` (sharing copies in `copies.py`), `interrogate`, `local`, `cost`, `config`, `batch`, `account` and `stats`.
|
|
41
|
+
|
|
42
|
+
Each command is a settings dataclass, a `resolve(options, ctx)` function from the parsed options, as a plain dict, to settings, and a `run(settings, ctx)` function that returns a result. `run` never prints and never calls `sys.exit`, so `batch` and future front ends call it in process. Flag parsing is tested through `resolve`, behaviour through `run` with a fake context.
|
|
43
|
+
|
|
44
|
+
`--dry-run` is a field of the settings, and for `batch` a field of the context, never an extra argv word. Paid commands prepare and price the request without sending it. If the balance cannot be read, the estimate assumes Opus; commands that return account data or look up tags still need a valid token. No output or login changes persist, apart from the tokenizer cache on first use. To find what the file system refuses, it makes the folders and the file it would write and removes again only the ones it made.
|
|
45
|
+
|
|
46
|
+
A dry run of several jobs, `batch --dry-run`, `grid --dry-run` and the check a grid makes before its first cell, runs each job as its own dry run. No job creates outputs for another, so it cannot use artifacts of earlier jobs in the dry run; predicting that would mean simulating the server, the ledger and the disk.
|
|
47
|
+
|
|
48
|
+
## One owner per rule
|
|
49
|
+
|
|
50
|
+
Every rule lives in one place. A second implementation of a rule drifts from the first unnoticed, so review checks this first.
|
|
51
|
+
|
|
52
|
+
| Rule | Owner |
|
|
53
|
+
|---|---|
|
|
54
|
+
| Request body fields, order and defaults | `request.py` |
|
|
55
|
+
| Prompt text: quality tags, UC presets, automatic text, literal ranges, weight syntax | `prompt.py` |
|
|
56
|
+
| Prompt tidying the user switches on: commas and spaces, Stable Diffusion weights, numeric closings | `tidy.py` |
|
|
57
|
+
| What each model supports | `models.py` |
|
|
58
|
+
| Prices, tiers and free allowances | `cost.py` |
|
|
59
|
+
| File name candidates from templates and folders | `naming.py` |
|
|
60
|
+
| Every write of a file: collision numbering, never overwriting, atomic replacement, file locks | `fs.py` |
|
|
61
|
+
| Text a request can carry | `values.py` |
|
|
62
|
+
| Settings stored in images and how they are read | `meta.py` |
|
|
63
|
+
| Arguments that rerun an image, and what they cannot bring back | `rerun.py` |
|
|
64
|
+
| Where the tokenizer files and Vibe encodings are kept, and the tokenizer download | `caches.py` |
|
|
65
|
+
| How imported settings land on a target model | `import_image.py` |
|
|
66
|
+
| Accounts, logins and token renewal, edits of the account store under its lock | `auth.py` |
|
|
67
|
+
| Balance before and after, the per-request limit, ledger entries | `charge.py`, `ledger.py` |
|
|
68
|
+
| Successful jobs and resuming | `batch.py` |
|
|
69
|
+
| Grid axes and their cells | `grid.py` |
|
|
70
|
+
| Waiting between batch jobs | `commands/batch.py` sets it, `commands/context.py` waits |
|
|
71
|
+
| Redaction and watermark drawing | `share.py` |
|
|
72
|
+
| Names and writing of sharing copies | `commands/copies.py` |
|
|
73
|
+
| Local ONNX models: loading, the SAM files and their hashes, the optional install | `local_models.py` |
|
|
74
|
+
| Error codes | `errors.py` |
|
|
75
|
+
|
|
76
|
+
Callers ask the owner. A pre-check that a file name is free calls the same function that will later name the file; it never rebuilds the name.
|
|
77
|
+
|
|
78
|
+
## Code rules
|
|
79
|
+
|
|
80
|
+
- **One concept per file, named after it.** Split by concept, never by size: a long file about one thing is fine; a second concept is the reason to split. No grab-bag `utils.py`.
|
|
81
|
+
- **Functions do one job.** About 40 lines needs a reason. Order inside a file: imports, public types, the public entry point, then its helpers in the order they are used.
|
|
82
|
+
- **No boolean switches between two behaviours.** If a flag changes what a function does rather than a detail of it, write two functions or pass an enum.
|
|
83
|
+
- **States are explicit.** Job states, import parts, charge outcomes and the like are enums or dataclasses, never loose strings or `None` meaning something.
|
|
84
|
+
- **Validate at trust boundaries only.** Command-line options, image metadata, server responses, job files and config files are checked where they enter. Code past that point trusts its inputs and carries no defensive branches for states that cannot happen.
|
|
85
|
+
- **Production code has no test hooks.** No branches that detect monkeypatching, no test-only modes or exports. Tests replace dependencies at a seam the code already has: the client, the clock, `fs`, `os`.
|
|
86
|
+
- **No compatibility shims before 1.0** unless a decision asks for one.
|
|
87
|
+
- **Never write the same lines twice.** Shared behaviour goes to the owner of the rule, not to a new helper next to one caller.
|
|
88
|
+
- **Top-level imports only.** No imports inside functions.
|
|
89
|
+
- **Comments say why**, in one line. A file starts with one line saying what it is for.
|
|
90
|
+
|
|
91
|
+
## Contract with callers
|
|
92
|
+
|
|
93
|
+
Scripts and agents depend on this, so it changes only with a decision recorded in the changelog.
|
|
94
|
+
|
|
95
|
+
- Standard output carries results only: one JSON object per command. Streaming commands (`batch`, `grid`, multi-file `meta`) print one JSON line per item and end with a summary line; every line has a `type` field (`job` or `summary` for `batch`) so a reader can dispatch without guessing from the keys. Logs and progress go to standard error.
|
|
96
|
+
- Field names and types in JSON results are part of the contract, including what an empty result looks like.
|
|
97
|
+
- Exit code 0 means success. Error codes in `errors.py` are public and are never renamed or removed.
|
|
98
|
+
- Files are created, never overwritten. A name that is taken gets the next free number, including one given with `-o`. A Vibe export probes its requested name before encoding; generated images fall back to a default name if the requested one cannot be written.
|
|
99
|
+
- A paid request is settled even when it fails or is interrupted: the result is saved if it arrived, the spend is read from the balance and written to the ledger.
|
|
100
|
+
- The same inputs and seed produce the same request as the official client. Deliberate differences are listed in [official-parity.md](official-parity.md#intentional-differences).
|
|
101
|
+
|
|
102
|
+
## Definition of done
|
|
103
|
+
|
|
104
|
+
A change is done when every item below holds. Review goes through them in order and stops at the first one that fails.
|
|
105
|
+
|
|
106
|
+
**Checks**
|
|
107
|
+
|
|
108
|
+
- `ruff check`, `ruff format --check` and `pytest` pass locally and in CI on Windows, macOS and Linux.
|
|
109
|
+
- No existing test was deleted or weakened to make the change pass. A test that changes because behaviour changed on purpose is named in the change description with the reason.
|
|
110
|
+
|
|
111
|
+
**Structure, enforced by `tests/test_architecture.py`**
|
|
112
|
+
|
|
113
|
+
- Imports follow the layer table: no module imports from a layer above it.
|
|
114
|
+
- The core imports nothing of the I/O layer but `errors`, `values` and `decode`.
|
|
115
|
+
- Only `fs.py` writes to disk: no `open` in a write mode, `Path.open`, `os.open`, `write_bytes`, `write_text`, `Image.save` to a path, `shutil` copies or moves, `os.replace` or `rename` anywhere else.
|
|
116
|
+
- Only `cli.py` touches `sys.stdin`, `sys.stdout`, `print` and `sys.exit`.
|
|
117
|
+
- Only the context reads the config file and creates the client: one call site each.
|
|
118
|
+
- No module under `commands/` imports `argparse` or `parser`.
|
|
119
|
+
- No imports inside functions.
|
|
120
|
+
|
|
121
|
+
**Structure, checked in review**
|
|
122
|
+
|
|
123
|
+
- Each rule touched by the change has one implementation, in the owner the table names. Review greps for the rule's other spellings (for file names: `exists()`, `-{n}`, `_{index}`) and finds none outside the owner.
|
|
124
|
+
- No state is stored on parsed options; commands receive settings.
|
|
125
|
+
- Functions longer than about 40 lines, other than option declarations in `parser.py`, are listed in the change description with the reason.
|
|
126
|
+
- No test hooks, compatibility aliases or duplicate constants in `src/`.
|
|
127
|
+
|
|
128
|
+
**Behaviour**
|
|
129
|
+
|
|
130
|
+
- Each fixed defect has a test that fails before the fix.
|
|
131
|
+
- New behaviour is tested at its seam and in the combinations listed under "Adding a feature".
|
|
132
|
+
- A dry run and the real run of the same command take the same path up to the first paid request.
|
|
133
|
+
|
|
134
|
+
**Documentation**
|
|
135
|
+
|
|
136
|
+
- usage.md, official-parity.md and `skills/nai-cli` describe the new behaviour; `tests/test_skill.py` passes.
|
|
137
|
+
|
|
138
|
+
## Adding a feature
|
|
139
|
+
|
|
140
|
+
1. Decide which layer it belongs to, and which existing owners it needs.
|
|
141
|
+
2. Put new rules in their owner. If no owner fits, the feature introduces a new concept and gets a new module.
|
|
142
|
+
3. Add the command under `commands/` and its options in `parser.py`.
|
|
143
|
+
4. Test each thing at its seam, once: a rule at its module, option handling through `resolve`, behaviour through `run` with a fake context, the JSON contract including the empty case. Then the combinations: inside batch, run a second time, and the next request after a failure.
|
|
144
|
+
5. Update [usage.md](usage.md), [official-parity.md](official-parity.md) if it touches request behaviour, and `skills/nai-cli`.
|