1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
|
.. DO NOT EDIT THIS FILE, GENERATED BY 'blender_help_extract_extension.py'
CHANGES TO THIS FILE MUST BE MADE IN BLENDER'S SOURCE CODE, SEE:
https://projects.blender.org/blender/blender-addons-contrib/src/branch/main/bl_pkg/bl_extension_cli.py
.. _command_line-args-extensions:
*********************************
Extensions Command Line Arguments
*********************************
.. NOTE: usage is commented, currently unhelpful.
blender --command extension [-h]
...
Command for managing Blender extensions.
options:
-h, --help show this help message and exit
subcommands:
`Package Management`_
:list: List all packages.
:sync: Synchronize with remote repositories.
:update: Upgrade any outdated packages.
:install: Install packages.
:install-file: Install package from file.
:remove: Remove packages.
`Repository Management`_
:repo-list: List repositories.
:repo-add: Add repository.
:repo-remove: Remove repository.
`Extension Creation`_
:build: Build a package.
:validate: Validate a package.
:server-generate: Create a listing from all packages.
Package Management
==================
.. _command-line-args-extension-list:
Subcommand: ``list``
--------------------
usage::
blender --command extension list [-h] [-s]
List packages from all enabled repositories.
options:
-h, --help show this help message and exit
-s, --sync Sync the remote directory before performing the action.
.. _command-line-args-extension-sync:
Subcommand: ``sync``
--------------------
usage::
blender --command extension sync [-h]
Download package information for remote repositories.
options:
-h, --help show this help message and exit
.. _command-line-args-extension-update:
Subcommand: ``update``
----------------------
usage::
blender --command extension update [-h] [-s]
Download and update any outdated packages.
options:
-h, --help show this help message and exit
-s, --sync Sync the remote directory before performing the action.
.. _command-line-args-extension-install:
Subcommand: ``install``
-----------------------
usage::
blender --command extension install [-h] [-s] [-e] [--no-prefs]
PACKAGES
positional arguments:
:PACKAGES: The packages to operate on (separated by ``,`` without spaces).
options:
-h, --help show this help message and exit
-s, --sync Sync the remote directory before performing the action.
-e, --enable Enable the extension after installation.
--no-prefs Treat the user-preferences as read-only,
preventing updates for operations that would otherwise modify them.
This means removing extensions or repositories for example, wont update the user-preferences.
.. _command-line-args-extension-install-file:
Subcommand: ``install-file``
----------------------------
usage::
blender --command extension install-file [-h] -r REPO [-e] [--no-prefs]
FILE
Install a package file into a user repository.
positional arguments:
:FILE: The packages file.
options:
-h, --help show this help message and exit
-r REPO, --repo REPO The repository identifier.
-e, --enable Enable the extension after installation.
--no-prefs Treat the user-preferences as read-only,
preventing updates for operations that would otherwise modify them.
This means removing extensions or repositories for example, wont update the user-preferences.
.. _command-line-args-extension-remove:
Subcommand: ``remove``
----------------------
usage::
blender --command extension remove [-h] [--no-prefs] PACKAGES
Disable & remove package(s).
positional arguments:
:PACKAGES: The packages to operate on (separated by ``,`` without spaces).
options:
-h, --help show this help message and exit
--no-prefs Treat the user-preferences as read-only,
preventing updates for operations that would otherwise modify them.
This means removing extensions or repositories for example, wont update the user-preferences.
Repository Management
=====================
.. _command-line-args-extension-repo-list:
Subcommand: ``repo-list``
-------------------------
usage::
blender --command extension repo-list [-h]
List all repositories stored in Blender's preferences.
options:
-h, --help show this help message and exit
.. _command-line-args-extension-repo-add:
Subcommand: ``repo-add``
------------------------
usage::
blender --command extension repo-add [-h] [--name NAME]
[--directory DIRECTORY]
[--url URL]
[--access-token ACCESS_TOKEN]
[--source SOURCE]
[--cache BOOLEAN] [--clear-all]
[--no-prefs]
ID
Add a new local or remote repository.
positional arguments:
:ID: The repository identifier.
options:
-h, --help show this help message and exit
--name NAME The name to display in the interface (optional).
--directory DIRECTORY
The directory where the repository stores local files (optional).
When omitted a directory in the users directory is automatically selected.
--url URL The URL, for remote repositories (optional).
When omitted the repository is considered "local"
as it is not connected to an external repository,
where packages may be installed by file or managed manually.
--access-token ACCESS_TOKEN
The access token to use for remote repositories which require a token.
--source SOURCE The type of source in ('USER', 'SYSTEM').
System repositories are managed outside of Blender and are considered read-only.
--cache BOOLEAN Use package cache (default=1).
--clear-all Clear all repositories before adding, simplifies test setup.
--no-prefs Treat the user-preferences as read-only,
preventing updates for operations that would otherwise modify them.
This means removing extensions or repositories for example, wont update the user-preferences.
.. _command-line-args-extension-repo-remove:
Subcommand: ``repo-remove``
---------------------------
usage::
blender --command extension repo-remove [-h] [--no-prefs] ID
Remove a repository.
positional arguments:
:ID: The repository identifier.
options:
-h, --help show this help message and exit
--no-prefs Treat the user-preferences as read-only,
preventing updates for operations that would otherwise modify them.
This means removing extensions or repositories for example, wont update the user-preferences.
Extension Creation
==================
.. _command-line-args-extension-build:
Subcommand: ``build``
---------------------
usage::
blender --command extension build [-h] [--source-dir SOURCE_DIR]
[--output-dir OUTPUT_DIR]
[--output-filepath OUTPUT_FILEPATH]
[--valid-tags VALID_TAGS_JSON]
[--split-platforms] [--verbose]
Build a package in the current directory.
options:
-h, --help show this help message and exit
--source-dir SOURCE_DIR
The package source directory containing a ``blender_manifest.toml`` manifest.
Default's to the current directory.
--output-dir OUTPUT_DIR
The package output directory.
Default's to the current directory.
--output-filepath OUTPUT_FILEPATH
The package output filepath (should include a ``.zip`` extension).
Defaults to ``{id}-{version}.zip`` using values from the manifest.
--valid-tags VALID_TAGS_JSON
Reference a file path containing valid tags lists.
If you wish to reference custom tags a ``.json`` file can be used.
The contents must be a dictionary of lists where the ``key`` matches the extension type.
For example:
``{"add-ons": ["Example", "Another"], "theme": ["Other", "Tags"]}``
To disable validating tags, pass in an empty path ``--valid-tags=""``.
--split-platforms Build a separate package for each platform.
Adding the platform as a file name suffix (before the extension).
This can be useful to reduce the upload size of packages that bundle large
platform-specific modules (``*.whl`` files).
--verbose Include verbose output.
.. _command-line-args-extension-validate:
Subcommand: ``validate``
------------------------
usage::
blender --command extension validate [-h]
[--valid-tags VALID_TAGS_JSON]
[SOURCE_PATH]
Validate the package meta-data in the current directory.
positional arguments:
:SOURCE_PATH: The package source path (either directory containing package files or the package archive).
This path must containing a ``blender_manifest.toml`` manifest.
Defaults to the current directory.
options:
-h, --help show this help message and exit
--valid-tags VALID_TAGS_JSON
Reference a file path containing valid tags lists.
If you wish to reference custom tags a ``.json`` file can be used.
The contents must be a dictionary of lists where the ``key`` matches the extension type.
For example:
``{"add-ons": ["Example", "Another"], "theme": ["Other", "Tags"]}``
To disable validating tags, pass in an empty path ``--valid-tags=""``.
.. _command-line-args-extension-server-generate:
Subcommand: ``server-generate``
-------------------------------
usage::
blender --command extension server-generate [-h] --repo-dir REPO_DIR
[--repo-config REPO_CONFIG]
[--html]
[--html-template HTML_TEMPLATE_FILE]
Generate a listing of all packages stored in a directory.
This can be used to host packages which only requires static-file hosting.
options:
-h, --help show this help message and exit
--repo-dir REPO_DIR The remote repository directory.
--repo-config REPO_CONFIG
An optional server configuration to include information which can't be detected.
Defaults to ``blender_repo.toml`` (in the repository directory).
This can be used to defined blocked extensions, for example ::
schema_version = "1.0.0"
[[blocklist]]
id = "my_example_package"
reason = "Explanation for why this extension was blocked"
[[blocklist]]
id = "other_extenison"
reason = "Another reason for why this is blocked"
--html Create a HTML file (``index.html``) as well as the repository JSON
to support browsing extensions online with static-hosting.
--html-template HTML_TEMPLATE_FILE
An optional HTML file path to override the default HTML template with your own.
The following keys will be replaced with generated contents:
- ``${body}`` is replaced the extensions contents.
- ``${date}`` is replaced the creation date.
|
