4. Using Turtles

Turtles is invoked at the command line as:

turtles

or as a Python module:

python -m lockss.turtles

Help messages and this document use turtles throughout, but the two invocation styles are interchangeable.

4.1. Turtles Commands

Turtles commands are in the subcommand style of programs like git, dnf/yum, apt/apt-get, and the like.

The available commands mirror the various Turtles Operations:

Operation	Command	Abbreviation
Build plugins	turtles build-plugin	turtles bp
Copyright statement	turtles copyright
Deploy plugins	turtles deploy-plugin	turtles dp
Software license	turtles license
Release plugins	turtles release-plugin	turtles rp
Subcommand tree	turtles tree
Version number	turtles version

You can see the synopsis by invoking turtles --help:

$ turtles --help
Usage: turtles [OPTIONS] COMMAND [ARGS]...

  ``turtles`` command.

Options:
  --color, --ansi / --no-color, --no-ansi
                 Strip out all colors and all ANSI codes from output.  [default:
                 color]
  --show-params  Show all CLI parameters, their provenance, defaults and value,
                 then exit.
  -h, --help     Show this message and exit.

Principal commands:
  build-plugin (bp)    Build (package and sign) plugins.
  deploy-plugin (dp)   Deploy plugins.
  release-plugin (rp)  Release (build and deploy) plugins.

Other commands:
  copyright            Show the copyright and exit.
  license              Show the software license and exit.
  tree                 show the command tree of your CLI
  version              Show the version number and exit.

4.1.1. turtles command

The top-level turtles command, alone, defaults to turtles --help.

Note

The --color/--ansi//--no-color/--no-ansi and --show-params options attach to the top-level turtles command only, not to a subcommand that may also be specified. For example, this is not valid:

$ turtles build-plugin --help --no-color
Usage: turtles build-plugin [OPTIONS]
Try 'turtles build-plugin --help' for help.

Error: No such option: --no-color

Instead, you should invoke turtles --no-color build-plugin --help.

4.1.2. turtles build-plugin

The turtles build-plugin (or alternatively turtles bp) command is used for building plugins, turning the source code found in plugin sets into signed JAR files ready to be deployed to plugin registries. It has its own --help/-h option:

$ turtles build-plugin --help
Usage: turtles build-plugin [OPTIONS]
Aliases: bp

  Build (package and sign) plugins.

Plugin identifier options:
  -i, --plugin-identifier IDENT  Add IDENT to the list of plugin identifiers to
                                 process.
  -I, --plugin-identifiers FILE  Add the plugin identifiers from FILE to the
                                 list of plugin identifiers to process.

Plugin building options:
  -s, --plugin-set FILE          Add the plugin set definitions from FILE to the
                                 loaded plugin sets.
  -S, --plugin-set-catalog FILE  Add the plugin set catalog definitions from
                                 FILE to the loaded plugin set catalogs.
                                 [default: (if no plugin sets or plugin set
                                 catalogs are specified:
                                 /home/docs/.config/lockss-turtles/plugin-set-
                                 catalog.yaml or /etc/lockss-turtles/plugin-set-
                                 catalog.yaml or /usr/local/share/lockss-
                                 turtles/plugin-set-catalog.yaml)]
  -c, --plugin-signing-credentials FILE
                                 Load the plugin signing credentials from FILE.
                                 [default: (/home/docs/.config/lockss-
                                 turtles/plugin-signing-credentials.yaml or
                                 /etc/lockss-turtles/plugin-signing-
                                 credentials.yaml or /usr/local/share/lockss-
                                 turtles/plugin-signing-credentials.yaml)]
  -P, --plugin-signing-password PASS
                                 Set the plugin signing password to PASS.
                                 [default: (interactive prompt)]

Output options:
  --headings / --no-headings  Set whether to include column headings in tabular
                              output.  [default: headings]
  -T, --table-format [asciidoc|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|html|jira|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|tsv|unsafehtml|vertical|youtrack]
                              Set the rendering of tables to the given style.
                              [default: simple]

Other options:
  --interactive / --non-interactive
              Set whether to allow interactive prompts for the plugin signing
              password or for first-time deployment confirmations.  [default:
              interactive]
  -h, --help  Show this message and exit.

The command requires:

• One or more plugin identifiers, from the Turtles Plugin Identifier Options (--plugin-identifier/-i, --plugin-identifiers/-I).

• One or more plugin sets, from the Turtles Plugin Set Options (--plugin-set/-s, --plugin-set-catalog/-S) or from a Default Plugin Set Catalog File.

• Plugin signing credentials, from the Turtles Plugin Signing Credentials Options (--plugin-signing-credentials/-c, --plugin-signing-password) or from a Default Plugin Signing Credentials File.

It also accepts Turtles Interactivity Options (--interactive//--non-interactive) and Turtles Output Format Options (--table-format/-T, --headings//--no-headings).

4.1.3. turtles copyright

The turtles copyright command outputs the copyright for Turtles:

$ turtles copyright
Copyright (c) 2000-2026, Board of Trustees of Leland Stanford Jr. University

4.1.4. turtles deploy-plugin

The turtles deploy-plugin (or alternatively turtles dp) command is used for deploying plugins, moving signed plugin JARs into appropriate plugin registry layers. It has its own --help/-h option:

$ turtles deploy-plugin --help
Usage: turtles deploy-plugin [OPTIONS]
Aliases: dp

  Deploy plugins.

Plugin JAR options:
  -j, --plugin-jar FILE   Add FILE to the list of plugin JARs to process.
  -J, --plugin-jars FILE  Add the plugin JARs from FILE to the list of plugin
                          JARs to process.

Plugin registry layer options:
  -l, --plugin-registry-layer IDENT
                    Add IDENT to the list of plugin registry layers to process.
  -L, --plugin-registry-layers FILE
                    Add the plugin registry layers from FILE to the list of
                    plugin registry layers to process.
  -p, --production  Add "production" to the list of plugin registry layers to
                    process.
  -t, --testing     Add "testing" to the list of plugin registry layers to
                    process.

Plugin deployment options:
  -r, --plugin-registry FILE  Add the plugin registry definitions from FILE to
                              the loaded plugin registries.
  -R, --plugin-registry-catalog FILE
                              Add the plugin registry catalog definitions from
                              FILE to the loaded plugin registry catalogs.
                              [default: (if no plugin registries or plugin
                              registry catalogs are specified:
                              /home/docs/.config/lockss-turtles/plugin-registry-
                              catalog.yaml or /etc/lockss-turtles/plugin-
                              registry-catalog.yaml or /usr/local/share/lockss-
                              turtles/plugin-registry-catalog.yaml)]

Output options:
  --headings / --no-headings  Set whether to include column headings in tabular
                              output.  [default: headings]
  -T, --table-format [asciidoc|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|html|jira|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|tsv|unsafehtml|vertical|youtrack]
                              Set the rendering of tables to the given style.
                              [default: simple]

Other options:
  --interactive / --non-interactive
              Set whether to allow interactive prompts for the plugin signing
              password or for first-time deployment confirmations.  [default:
              interactive]
  -h, --help  Show this message and exit.

The command requires:

• One or more plugin JAR files, from the Turtles Plugin JAR Options (--plugin-jar/-j, --plugin-jars/-J).

• One or more plugin registries, from the Turtles Plugin Registry Options (--plugin-registry/-r, --plugin-registry-catalog/-R) or from a Default Plugin Registry Catalog File.

• One or more plugin registry layers, from the Turtles Plugin Registry Layer Options (--plugin-registry-layer/-l, --plugin-registry-layers/-L, --testing/-t, --production/-p).

It also accepts Turtles Interactivity Options (--interactive//--non-interactive) and Turtles Output Format Options (--table-format/-T, --headings//--no-headings).

4.1.5. turtles license

The turtles license command outputs the software license for Turtles:

$ turtles license
Copyright (c) 2000-2026, Board of Trustees of Leland Stanford Jr. University

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors
may be used to endorse or promote products derived from this software without
specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

4.1.6. turtles release-plugin

The turtles release-plugin (or alternatively turtles rp) command is used for releasing plugins (building then deploying plugins), that is, turning the source code found in plugin sets into signed JAR files, and then moving them into appropriate plugin registry layers. It has its own --help/-h option:

$ turtles release-plugin --help
Usage: turtles release-plugin [OPTIONS]
Aliases: rp

  Release (build and deploy) plugins.

Plugin identifier options:
  -i, --plugin-identifier IDENT  Add IDENT to the list of plugin identifiers to
                                 process.
  -I, --plugin-identifiers FILE  Add the plugin identifiers from FILE to the
                                 list of plugin identifiers to process.

Plugin registry layer options:
  -l, --plugin-registry-layer IDENT
                    Add IDENT to the list of plugin registry layers to process.
  -L, --plugin-registry-layers FILE
                    Add the plugin registry layers from FILE to the list of
                    plugin registry layers to process.
  -p, --production  Add "production" to the list of plugin registry layers to
                    process.
  -t, --testing     Add "testing" to the list of plugin registry layers to
                    process.

Plugin building options:
  -s, --plugin-set FILE          Add the plugin set definitions from FILE to the
                                 loaded plugin sets.
  -S, --plugin-set-catalog FILE  Add the plugin set catalog definitions from
                                 FILE to the loaded plugin set catalogs.
                                 [default: (if no plugin sets or plugin set
                                 catalogs are specified:
                                 /home/docs/.config/lockss-turtles/plugin-set-
                                 catalog.yaml or /etc/lockss-turtles/plugin-set-
                                 catalog.yaml or /usr/local/share/lockss-
                                 turtles/plugin-set-catalog.yaml)]
  -c, --plugin-signing-credentials FILE
                                 Load the plugin signing credentials from FILE.
                                 [default: (/home/docs/.config/lockss-
                                 turtles/plugin-signing-credentials.yaml or
                                 /etc/lockss-turtles/plugin-signing-
                                 credentials.yaml or /usr/local/share/lockss-
                                 turtles/plugin-signing-credentials.yaml)]
  -P, --plugin-signing-password PASS
                                 Set the plugin signing password to PASS.
                                 [default: (interactive prompt)]

Plugin deployment options:
  -r, --plugin-registry FILE  Add the plugin registry definitions from FILE to
                              the loaded plugin registries.
  -R, --plugin-registry-catalog FILE
                              Add the plugin registry catalog definitions from
                              FILE to the loaded plugin registry catalogs.
                              [default: (if no plugin registries or plugin
                              registry catalogs are specified:
                              /home/docs/.config/lockss-turtles/plugin-registry-
                              catalog.yaml or /etc/lockss-turtles/plugin-
                              registry-catalog.yaml or /usr/local/share/lockss-
                              turtles/plugin-registry-catalog.yaml)]

Output options:
  --headings / --no-headings  Set whether to include column headings in tabular
                              output.  [default: headings]
  -T, --table-format [asciidoc|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|html|jira|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|tsv|unsafehtml|vertical|youtrack]
                              Set the rendering of tables to the given style.
                              [default: simple]

Other options:
  --interactive / --non-interactive
              Set whether to allow interactive prompts for the plugin signing
              password or for first-time deployment confirmations.  [default:
              interactive]
  -h, --help  Show this message and exit.

As a command that combines plugin building and plugin deployment operations, this command requires:

• One or more plugin identifiers, from the Turtles Plugin Identifier Options (--plugin-identifier/-i, --plugin-identifiers/-I).

• One or more plugin sets, from the Turtles Plugin Set Options (--plugin-set/-s, --plugin-set-catalog/-S) or from a Default Plugin Set Catalog File.

• Plugin signing credentials, from the Turtles Plugin Signing Credentials Options (--plugin-signing-credentials/-c, --plugin-signing-password) or from a Default Plugin Signing Credentials File.

• One or more plugin registries, from the Turtles Plugin Registry Options (--plugin-registry/-r, --plugin-registry-catalog/-R) or from a Default Plugin Registry Catalog File.

• One or more plugin registry layers, from the Turtles Plugin Registry Layer Options (--plugin-registry-layer/-l, --plugin-registry-layers/-L, --testing/-t, --production/-p).

It also accepts Turtles Interactivity Options (--interactive//--non-interactive) and Turtles Output Format Options (--table-format/-T, --headings//--no-headings).

4.1.7. turtles tree

The turtles tree command displays the Turtles subcommand tree:

$ turtles tree
turtles - ``turtles`` command.
├── build-plugin - ``turtles build-plugin`` command.
├── copyright - ``turtles copyright`` command.
├── deploy-plugin - ``turtles deploy-plugin`` command.
├── license - ``turtles license`` command.
├── release-plugin - ``turtles release-plugin`` command.
├── tree - show the command tree of your CLI
└── version - ``turtles version`` command.

4.1.8. turtles version

The turtles version command outputs the Turtles version number:

$ turtles version
0.7.0

4.2. Turtles Options

4.2.1. Turtles Interactivity Options

Some Turtles commands may prompt for input interactively:

• Turtles Plugin Building Operations will prompt for a plugin signing password unless the --plugin-signing-password option was specified.

• Turtles Plugin Deployment Operations will prompt for confirmation before deploying a plugin to a plugin registry layer for the very first time.

The --non-interactive option prevents these interactive prompts.

4.2.2. Turtles Output Format Options

Note

As of version 0.7.0, --output-format has been renamed to --table-format/-T.

Turtles's tabular output is performed by the Click Extra library, via the --table-format/-T and --headings//--no-headings options. See its documentation or the --help/-h message of any Turtles plugin building or plugin deployment command for a list of the various output formats available in the --table-format/-T option. The default value is simple. This option accepts a single argument, with or without an equals sign:

# Without an equals sign
turtles ... --table-format outline

# With an equals sign
turtles ... --table-format=outline

The --headings//--no-headings options control whether or not column headings are displayed, respectively. The default is --headings.

4.2.3. Turtles Plugin Identifier Options

Note

As of version 0.7.0, --plugin-identifier/-i and --plugin-identifiers/-I options only accept one argument at a time each, rather than one or more each.

Commands for Turtles Plugin Building Operations expect one or more plugin identifiers, for instance edu.myuniversity.plugin.MyFirstPlugin. The set of plugin identifiers to process is derived from:

• The plugin identifiers specified in --plugin-identifier/-i options. Each --plugin-identifier/-i option accepts one plugin identifier. The long option --plugin-identifier and its argument can optionally be joined by an equals sign.

• The plugin identifiers listed in the files specified as --plugin-identifiers/-I options. Each --plugin-identifiers/-I option accepts one file path. The long option --plugin-identifiers and its argument can optionally be joined by an equals sign.

Examples:

# --plugin-identifier without an equals sign
turtles build-plugin --plugin-identifier edu.myuniversity.plugin.MyFirstPlugin \
                     --plugin-identifier edu.myuniversity.plugin.MySecondPlugin \
                     ...

# Same, but with --plugin-identifier abbreviated to -i
turtles build-plugin -i edu.myuniversity.plugin.MyFirstPlugin \
                     -i edu.myuniversity.plugin.MySecondPlugin \
                     ...

# --plugin-identifier with an equals sign
turtles build-plugin --plugin-identifier=edu.myuniversity.plugin.MyFirstPlugin \
                     --plugin-identifier=edu.myuniversity.plugin.MySecondPlugin \
                     ...

# --plugin-identifiers without an equals sign
turtles build-plugin --plugin-identifiers list1.txt \
                     --plugin-identifiers list2.txt \
                     ...

# Same, but with --plugin-identifiers abbreviated to -I
turtles build-plugin -I list1.txt -I list2.txt ...

# --plugin-identifiers with an equals sign
turtles build-plugin --plugin-identifiers=list1.txt \
                     --plugin-identifiers=list2.txt \
                     ...

4.2.4. Turtles Plugin JAR Options

Note

As of version 0.7.0, --plugin-jar/-j and --plugin-jars/-J options only accept one argument at a time each, rather than one or more each.

Commands for Turtles Plugin Deployment Operations expect one or more plugin JAR file paths. The set of plugin JARs to process is derived from:

• The plugin JAR file paths specified in --plugin-jar/-j options. Each --plugin-jar/-j option accepts one plugin JAR file path. The long option --plugin-jar and its argument can optionally be joined by an equals sign.

• The plugin JAR files paths listed in the files specified as --plugin-jars/-J options. Each --plugin-jars/-J option accepts one file paths. The long option --plugin-jars and its argument can optionally be joined by an equals sign.

Examples:

# --plugin-jar without an equals sign
turtles deploy-plugin --plugin-jar edu.myuniversity.plugin.MyFirstPlugin.jar \
                      --plugin-jar edu.myuniversity.plugin.MySecondPlugin.jar \
                      ...

# Same, but with --plugin-jar abbreviated to -j
turtles deploy-plugin -j edu.myuniversity.plugin.MyFirstPlugin.jar \
                      -j edu.myuniversity.plugin.MySecondPlugin.jar \
                      ...

# --plugin-jar with an equals sign
turtles deploy-plugin --plugin-jar=edu.myuniversity.plugin.MyFirstPlugin.jar \
                      --plugin-jar=edu.myuniversity.plugin.MySecondPlugin.jar \
                      ...

# --plugin-jars without an equals sign
turtles deploy-plugin --plugin-jars list1.txt --plugin-jars list2.txt ...

# Same, but with --plugin-jars abbreviated to -J
turtles deploy-plugin -J list1.txt -J list2.txt ...

# --plugin-jars with an equals sign
turtles deploy-plugin --plugin-jars=list1.txt \
                      --plugin-jars=list2.txt \
                      ...

4.2.5. Turtles Plugin Registry Options

Note

As of version 0.7.0, --plugin-registry/-r and --plugin-registry-catalog/-R options only accept one argument at a time each, rather than one or more each.

Commands for Turtles Plugin Deployment Operations need one or more plugin registries. The loaded plugin registries are derived from:

• The plugin registry definitions found in files specified in --plugin-registry/-r options. Each --plugin-registry/-r option accepts one file path. The long option --plugin-registry and its argument can optionally be joined by an equals sign.

• The plugin registries listed in the plugin registry catalog definitions found in files specified in --plugin-registry-catalog/-R options. Each --plugin-registry-catalog/-R option accepts one file path. The long option --plugin-registry-catalog and its argument can optionally be joined by an equals sign.

If no plugin registry nor plugin registry catalog is specified with --plugin-registry/-r or --plugin-registry-catalog/-R options (respectively), Turtles loads a Default Plugin Registry Catalog File.

4.2.6. Turtles Plugin Registry Layer Options

Note

As of version 0.7.0, --plugin-registry-layer/-l and --plugin-registry-layers/-L options only accept one argument at a time each, rather than one or more each.

Commands for Turtles Plugin Deployment Operations expect one or more plugin registry layers, for instance testing or production. The set of plugin registry layers to process is derived from:

• The plugin registry layer identifiers specified in --plugin-registry-layer/-l options. Each --plugin-registry-layer/-l option accepts one plugin registry layer identifier. The long option --plugin-registry-layer and its argument can optionally be joined by an equals sign.

• The plugin registry layer identifiers listed in the files specified as --plugin-registry-layers/-L options. Each --plugin-registry-layers/-L option accepts one file path. The long option --plugin-registry-layers and its argument can optionally be joined by an equals sign.

• The --testing/-t options, which add testing to the set of plugin registry layers to process.

• The --production/-p options, which add production to the set of plugin registry layers to process.

Examples:

# --plugin-registry-layer without an equals sign
turtles deploy-plugin ... --plugin-registry-layer testing \
                          --plugin-registry-layer production \
                          ...

# Same, but with --plugin-registry-layer abbreviated to -l
turtles deploy-plugin ... -l testing -l production ...

# --plugin-registry-layer with an equals sign
turtles deploy-plugin ... --plugin-registry-layer=testing \
                          --plugin-registry-layer=production \
                          ...

# Using --testing as a synonym for --plugin-registry-layer=testing
# and --production as a synonym for --plugin-registry-layer=production
turtles deploy-plugin ... --testing --production ...

# Same, but with --testing abbreviated to -t
# and --production abbreviated to -p
turtles deploy-plugin ... -t -p ...

# Same, but combining -t and -p into one
turtles deploy-plugin ... -tp ...

# --plugin-registry-layers without an equals sign
turtles deploy-plugin ... --plugin-registry-layers list1.txt \
                          --plugin-registry-layers list2.txt \
                          ...

# Same, but with --plugin-registry-layers abbreviated to -L
turtles deploy-plugin ... -L list1.txt -L list2.txt ...

# --plugin-registry-layers with an equals sign
turtles deploy-plugin ... --plugin-registry-layers=list1.txt \
                          --plugin-registry-layers=list2.txt \
                          ...

4.2.7. Turtles Plugin Set Options

Commands for Turtles Plugin Building Operations need one or more plugin sets. The loaded plugin sets are derived from:

• The plugin set definitions found in files specified in --plugin-set/-s options. Each --plugin-set/-s option accepts one file path. The long option --plugin-set and its argument can optionally be joined by an equals sign.

• The plugin sets listed in the plugin set catalog definitions found in files specified in --plugin-set-catalog/-S options. Each --plugin-set-catalog/-S option accepts one file path. The long option --plugin-set-catalog and its argument can optionally be joined by an equals sign.

If no plugin set nor plugin set catalog is specified with --plugin-set/-s or --plugin-set-catalog/-S options (respectively), Turtles loads a Default Plugin Registry Catalog File.

4.2.8. Turtles Plugin Signing Credentials Options

Commands for Turtles Plugin Building Operations need plugin signing credentials and a plugin signing password.

The plugin signing credentials are derived from the --plugin-signing-credentials/-c option or, if not specified, from a Default Plugin Signing Credentials File. The long option --plugin-signing-credentials and its argument can optionally be joined by an equals sign.

The plugin signing password can be given interactively (unless the --non-interactive option is specified; see Turtles Interactivity Options), or passed at the command line with the --plugin-signing-password option. The long option --plugin-signing-password and its argument can optionally be joined by an equals sign.