Getting Started

Dodeca Shell (Dshell) is a command-line utility that helps you work with a Dodeca repository. It connects directly to the repository database (without going through the Dodeca server itself). Various actions can be performed on a repository, including viewing, exporting, importing, and searching for data.

Dshell is packaged as a self-contained runnable JAR file. In order to run it, you need to have Java 1.8+ installed on your system. It is much more convenient to run when you have java available on your system path, so that you only need to type java to run it, as opposed to a fully qualified path.

You can quickly test if Java is available on the current path as well as of a new enough version by trying to run the Java version command from a commmand-line:

java -version

If Java is installed and available on the path, you may see output like the following:

java version "1.8.0_25"
Java(TM) SE Runtime Environment (build 1.8.0_25-b17)
Java HotSpot(TM) 64-Bit Server VM (build 25.25-b02, mixed mode)

You can run dshell by executing the following command:

java -Dloader.path=lib/ -jar dodeca-shell.jar

This command defines a variable named loader.path and sets it to the lib subfolder of the current working directory. This setting sets the folder that Dshell should look in for additional JDBC drivers that may be needed to connect to your Dodeca repository. You will likely need additional JAR files for your repository, based on its database technology (such as Oracle, Microsoft SQL Server, DB2, MySQL, and others).

If everything works correctly, you will see Dshell start up similar to the following:

       __     __         ____
  ____/ /____/ /_  ___  / / /
 / __  / ___/ __ \/ _ \/ / /
/ /_/ (__  ) / / /  __/ / /
\__,_/____/_/ /_/\___/_/_/
You are connected to an internal repository. Use the connect command to connect to a Dodeca repository
Type 'help connect' for information on how to use the connect command
dshell/:>

By default, dshell starts up and is connected to an internal repository that does not have any objects in it. You can use this workspace to facilitate certain types of testing, but most likely you will need and want to connect it to your own repository.

Connecting To Your Dodeca Repository

The easiest way to connect to a repository is to create a properties file with the connection settings in it. This can be as simple as a file with the following contents:

hibernate.connection.url = jdbc:mysql://server/dodeca?noDatetimeStringSync=true
hibernate.connection.username = dodeca
hibernate.connection.password = password

The preceding example is for a repository inside a MySQL database, therefore the JDBC URL is formatted specifically for MySQL. The URL format for other database types typically varies. You can use the same setting from your existing hibernate.properties file configured for your Dodeca server or attempt to create the URL yourself. The username and password fields are defined with the plaintext version of the password.

For convenience, you can use the suffix .dodeca.properties on your connection file, for a total file name such as mysql-dev.dodeca.properties. This allows you to use the list-connections command in the shell, which will list all of the files in the current directory that have this suffix. You may then use the connect command to refer to this short version of the file, such as:

connect mysql-dev

You may use the fully-qualified name of the file as well. You can switch between different repository connections during a single shell session, even if those connections are different database technologies (so long as the appropriate JDBC drivers are available, of course).

Most shell commands require having specified a tenant to work with by using the use command. For example, to set the tenant to SAMPLE, you would type:

use SAMPLE

Assuming that a tenant named SAMPLE exists, the shell prompt will update to indicate the current tenant:

dshell/SAMPLE:>

Using Tab-based Auto-completion

Many commands in the shell support tab-based auto-completion. This can make entering artfiact IDs, tenants, commands, and file names much more quick and less error prone.

For example, consider when there are a number of tenants available, such as by using the list-tenants command:

dshell/SAMPLE:>list-tenants
+---------------------------+
|Tenant                     |
+---------------------------+
|DEMOWARE                   |
|SAMPLE                     |
+---------------------------+

You may then wish to switch to the DEMOWARE tenant. You can have the shell provide you a list of items to select from, or a list of items based on what you have already typed in. For example, upon typing use DE followed by pressing the tab key, the shell will finish off the text by using the matching tenant (in this case, DEMOWARE), and you can then press enter to execute the command.

If you have not started typing the text for an item, the shell may prompt your for the parameter name first, which you can select and press tab again in order to get the list of all available options.

Scripting

The shell offers limited scripting/automation capabilities by way of running the shell with an additional parameter that specifies a list of commands to run sequentially. For instance, you may wish to automate a process that connects to your repository and exports all of the comments for a certain Dodeca tenant named SAMPLE. The sequence of commands for accomplishing this would be the following:

connect mysql-dev
use SAMPLE
export-comments --file comment_export.xml

You can then put these lines into a file named export_comments.dshell and then run it with the following command:

java -Dloader.path=lib/ -jar dodeca-shell.jar @export_comments.dshell

Note that @ symbol in front of the scripting filename (@export_comments.dshell).

Script files are read as UTF-8 and executed sequentially. Blank lines and lines whose first non-whitespace characters are // are ignored. A command can continue onto the next line by ending the line with a backslash.

Scripts support variables set by earlier commands:

set --name TENANT --value SAMPLE
use ${TENANT}

Variable substitution is a scripting feature and is not performed for commands entered at the interactive prompt. Variables remain available to subsequent script files when multiple @file arguments are supplied to the same shell invocation.

Script execution is fail-fast. An undefined variable, malformed or incomplete command, unavailable command, or command failure stops the current script and prevents later script files from running. Script input errors identify the source file and line number, and the process returns a nonzero exit code. Commands that completed before the failure are not rolled back, so scripts should use existing dry-run or validation options where commands provide them and should be designed to be safely restartable.

Commands that attempt to prompt while a script is running fail immediately with the script filename and line number. They never wait on standard input. Commands that need a password can instead use a secret-source option:

// Read a native password from an environment variable
principal-native-admin-create --username automation --secret-source env:DODECA_NATIVE_PASSWORD
// Read a repository password from a UTF-8 file
connect --connection-file production.dodeca.properties --password-secret-source file:/run/secrets/dodeca-password

Secret references use env:NAME or file:PATH; the secret itself is never a command-line argument. A secret file may end with one line ending, which is removed. Empty secrets, missing environment variables, unreadable files, inline values, and unknown source types are rejected. Restrict secret-file permissions and remember that environment variables may be visible to privileged process-inspection tools.

set --env imports environment variables for script substitution without printing their values. Environment-derived values appear as <redacted> when variables are listed. Explicit values supplied to the ordinary set --value option are not treated as secrets and may be displayed.

For non-terminal execution, Dodeca Shell automatically disables ANSI output and its startup banner. --no-color provides the same ANSI suppression explicitly. Direct command data, tables, and machine-readable output are written to standard output; operational logging, warnings, and errors are written to standard error.

The list-artifacts and jdbc-driver-list inspection commands accept --output JSON in addition to their default tables. JSON contains only the properties selected by those commands and is written to standard output.

Use --execution-report FILE with one or more script files to atomically write a versioned JSON completion report:

java -Dloader.path=lib/ -jar dodeca-shell.jar \
  --execution-report execution-report.json \
  @maintenance.dshell

The report records status, timestamps, duration, requested and completed script counts, and failure source/line details. The report must be a file so it cannot corrupt command output. A report is attempted for both successful and failed executions; failure to write a success report fails the invocation.

Automation safety

Dodeca Shell does not apply one universal confirmation or dry-run policy to historical commands. Check help <command> before automating a mutation.

  • Commands such as delete-tenant and delete-comments require their documented confirmation flag.

  • delete-saved-view prompts unless --force is supplied. Because scripts cannot prompt, a script must make the destructive intent explicit with --force or the command fails.

  • Some older destructive commands, including individual and bulk artifact deletion, do not prompt. Treat their presence in a script as authorization to mutate immediately.

  • --dry-run is command-specific. Where it exists, it previews only the behavior documented by that command; it is not a transaction spanning the script.

  • A script failure does not roll back commands that already completed. Prefer commands with validation, dry-run, skip-if-unchanged, or explicit replacement controls, and design automation so rerunning after partial completion is safe.

  • Idempotency is command-specific. Inspection commands are safe to repeat, but create/import/delete commands may fail, replace data, or do nothing depending on their documented options and current repository state.

For unattended or AI-driven maintenance, begin with inspection and dry-run commands, capture an execution report, require explicit confirmation flags in reviewed scripts, and retain the script and report as an operational record.

Getting Help With Commands

You can get a list of all available commands by typing help. You can get help and parameter information by typing help followed by the command name. For instance, to get help on the export-comments command, type:

help export-comments

You will then be presented with help like the following:

NAME
	export-comments - Export comments

SYNOPSYS
	export-comments [--file] file  [[--author] string]  [[--include-key-spec]
	comment-key-spec]  [[--exclude-key-spec] comment-key-spec]

OPTIONS
	--file or -F  file

		[Mandatory]

	--author  string

		[Optional, default = <none>]

	--include-key-spec  comment-key-spec

		[Optional, default = <none>]

	--exclude-key-spec  comment-key-spec

		[Optional, default = <none>]