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.
Files changed (118) hide show
  1. nai_cli-0.1.0/.gitignore +7 -0
  2. nai_cli-0.1.0/CHANGELOG.md +5 -0
  3. nai_cli-0.1.0/LICENSE +21 -0
  4. nai_cli-0.1.0/PKG-INFO +105 -0
  5. nai_cli-0.1.0/README.md +68 -0
  6. nai_cli-0.1.0/README.zh.md +68 -0
  7. nai_cli-0.1.0/THIRD_PARTY_NOTICES.md +56 -0
  8. nai_cli-0.1.0/docs/architecture.md +144 -0
  9. nai_cli-0.1.0/docs/official-parity.md +175 -0
  10. nai_cli-0.1.0/docs/usage.md +363 -0
  11. nai_cli-0.1.0/pyproject.toml +93 -0
  12. nai_cli-0.1.0/skills/nai-cli/SKILL.md +85 -0
  13. nai_cli-0.1.0/skills/nai-cli/references/batch.md +15 -0
  14. nai_cli-0.1.0/skills/nai-cli/references/inpaint.md +33 -0
  15. nai_cli-0.1.0/skills/nai-cli/references/vibes.md +17 -0
  16. nai_cli-0.1.0/src/nai_cli/__init__.py +3 -0
  17. nai_cli-0.1.0/src/nai_cli/__main__.py +5 -0
  18. nai_cli-0.1.0/src/nai_cli/api.py +529 -0
  19. nai_cli-0.1.0/src/nai_cli/auth.py +240 -0
  20. nai_cli-0.1.0/src/nai_cli/batch.py +126 -0
  21. nai_cli-0.1.0/src/nai_cli/caches.py +56 -0
  22. nai_cli-0.1.0/src/nai_cli/charge.py +231 -0
  23. nai_cli-0.1.0/src/nai_cli/cli.py +110 -0
  24. nai_cli-0.1.0/src/nai_cli/comfyui.py +194 -0
  25. nai_cli-0.1.0/src/nai_cli/commands/__init__.py +61 -0
  26. nai_cli-0.1.0/src/nai_cli/commands/account.py +79 -0
  27. nai_cli-0.1.0/src/nai_cli/commands/batch.py +142 -0
  28. nai_cli-0.1.0/src/nai_cli/commands/config.py +57 -0
  29. nai_cli-0.1.0/src/nai_cli/commands/context.py +201 -0
  30. nai_cli-0.1.0/src/nai_cli/commands/copies.py +138 -0
  31. nai_cli-0.1.0/src/nai_cli/commands/cost.py +70 -0
  32. nai_cli-0.1.0/src/nai_cli/commands/generate.py +257 -0
  33. nai_cli-0.1.0/src/nai_cli/commands/generation.py +550 -0
  34. nai_cli-0.1.0/src/nai_cli/commands/grid.py +99 -0
  35. nai_cli-0.1.0/src/nai_cli/commands/image_tools.py +248 -0
  36. nai_cli-0.1.0/src/nai_cli/commands/interrogate.py +77 -0
  37. nai_cli-0.1.0/src/nai_cli/commands/lint.py +24 -0
  38. nai_cli-0.1.0/src/nai_cli/commands/local.py +62 -0
  39. nai_cli-0.1.0/src/nai_cli/commands/meta.py +102 -0
  40. nai_cli-0.1.0/src/nai_cli/commands/models.py +62 -0
  41. nai_cli-0.1.0/src/nai_cli/commands/output.py +165 -0
  42. nai_cli-0.1.0/src/nai_cli/commands/redact.py +48 -0
  43. nai_cli-0.1.0/src/nai_cli/commands/references.py +87 -0
  44. nai_cli-0.1.0/src/nai_cli/commands/spec.py +245 -0
  45. nai_cli-0.1.0/src/nai_cli/commands/stats.py +54 -0
  46. nai_cli-0.1.0/src/nai_cli/commands/strip.py +15 -0
  47. nai_cli-0.1.0/src/nai_cli/commands/tags.py +32 -0
  48. nai_cli-0.1.0/src/nai_cli/commands/texts.py +71 -0
  49. nai_cli-0.1.0/src/nai_cli/commands/vibe.py +151 -0
  50. nai_cli-0.1.0/src/nai_cli/commands/watermark.py +70 -0
  51. nai_cli-0.1.0/src/nai_cli/config.py +369 -0
  52. nai_cli-0.1.0/src/nai_cli/cost.py +114 -0
  53. nai_cli-0.1.0/src/nai_cli/data/random_prompt.json +2536 -0
  54. nai_cli-0.1.0/src/nai_cli/decode.py +87 -0
  55. nai_cli-0.1.0/src/nai_cli/enhance.py +137 -0
  56. nai_cli-0.1.0/src/nai_cli/errors.py +40 -0
  57. nai_cli-0.1.0/src/nai_cli/fs.py +209 -0
  58. nai_cli-0.1.0/src/nai_cli/grid.py +244 -0
  59. nai_cli-0.1.0/src/nai_cli/images.py +250 -0
  60. nai_cli-0.1.0/src/nai_cli/import_image.py +235 -0
  61. nai_cli-0.1.0/src/nai_cli/inpaint.py +476 -0
  62. nai_cli-0.1.0/src/nai_cli/ledger.py +146 -0
  63. nai_cli-0.1.0/src/nai_cli/lint.py +302 -0
  64. nai_cli-0.1.0/src/nai_cli/local_models.py +135 -0
  65. nai_cli-0.1.0/src/nai_cli/meta.py +606 -0
  66. nai_cli-0.1.0/src/nai_cli/models.py +308 -0
  67. nai_cli-0.1.0/src/nai_cli/naming.py +426 -0
  68. nai_cli-0.1.0/src/nai_cli/parser.py +611 -0
  69. nai_cli-0.1.0/src/nai_cli/pixel_snap.py +525 -0
  70. nai_cli-0.1.0/src/nai_cli/presets.py +276 -0
  71. nai_cli-0.1.0/src/nai_cli/prompt.py +457 -0
  72. nai_cli-0.1.0/src/nai_cli/random_prompt.py +285 -0
  73. nai_cli-0.1.0/src/nai_cli/request.py +621 -0
  74. nai_cli-0.1.0/src/nai_cli/rerun.py +177 -0
  75. nai_cli-0.1.0/src/nai_cli/resample.py +133 -0
  76. nai_cli-0.1.0/src/nai_cli/sam.py +63 -0
  77. nai_cli-0.1.0/src/nai_cli/share.py +392 -0
  78. nai_cli-0.1.0/src/nai_cli/sheet.py +86 -0
  79. nai_cli-0.1.0/src/nai_cli/tagger.py +464 -0
  80. nai_cli-0.1.0/src/nai_cli/tags.py +44 -0
  81. nai_cli-0.1.0/src/nai_cli/tidy.py +176 -0
  82. nai_cli-0.1.0/src/nai_cli/tokenizer.py +313 -0
  83. nai_cli-0.1.0/src/nai_cli/values.py +114 -0
  84. nai_cli-0.1.0/src/nai_cli/vibe.py +464 -0
  85. nai_cli-0.1.0/tests/conftest.py +68 -0
  86. nai_cli-0.1.0/tests/helpers.py +101 -0
  87. nai_cli-0.1.0/tests/samples.py +117 -0
  88. nai_cli-0.1.0/tests/test_accounts.py +469 -0
  89. nai_cli-0.1.0/tests/test_api.py +509 -0
  90. nai_cli-0.1.0/tests/test_architecture.py +351 -0
  91. nai_cli-0.1.0/tests/test_batch.py +456 -0
  92. nai_cli-0.1.0/tests/test_charge.py +360 -0
  93. nai_cli-0.1.0/tests/test_cli.py +124 -0
  94. nai_cli-0.1.0/tests/test_comfyui.py +138 -0
  95. nai_cli-0.1.0/tests/test_config.py +113 -0
  96. nai_cli-0.1.0/tests/test_enhance.py +129 -0
  97. nai_cli-0.1.0/tests/test_files.py +656 -0
  98. nai_cli-0.1.0/tests/test_generate.py +177 -0
  99. nai_cli-0.1.0/tests/test_grid.py +230 -0
  100. nai_cli-0.1.0/tests/test_import.py +432 -0
  101. nai_cli-0.1.0/tests/test_inpaint.py +362 -0
  102. nai_cli-0.1.0/tests/test_ledger.py +248 -0
  103. nai_cli-0.1.0/tests/test_local_models.py +400 -0
  104. nai_cli-0.1.0/tests/test_locks.py +77 -0
  105. nai_cli-0.1.0/tests/test_meta_lint.py +714 -0
  106. nai_cli-0.1.0/tests/test_naming.py +143 -0
  107. nai_cli-0.1.0/tests/test_pixel_snap.py +91 -0
  108. nai_cli-0.1.0/tests/test_prompt.py +173 -0
  109. nai_cli-0.1.0/tests/test_random_prompt.py +121 -0
  110. nai_cli-0.1.0/tests/test_request.py +358 -0
  111. nai_cli-0.1.0/tests/test_resample.py +70 -0
  112. nai_cli-0.1.0/tests/test_roundtrip.py +87 -0
  113. nai_cli-0.1.0/tests/test_share.py +304 -0
  114. nai_cli-0.1.0/tests/test_skill.py +47 -0
  115. nai_cli-0.1.0/tests/test_tags.py +126 -0
  116. nai_cli-0.1.0/tests/test_tokenizer.py +348 -0
  117. nai_cli-0.1.0/tests/test_v4.py +58 -0
  118. nai_cli-0.1.0/tests/test_vibe.py +722 -0
@@ -0,0 +1,7 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ .venv/
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ dist/
7
+ tests/private/
@@ -0,0 +1,5 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 - 2026-11-20
4
+
5
+ First release.
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).
@@ -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`.