diff --git a/CLI-Reference.md b/CLI-Reference.md new file mode 100644 index 0000000..3964c5b --- /dev/null +++ b/CLI-Reference.md @@ -0,0 +1,143 @@ +# CLI Reference + +The general usage is shown with `dtmt --help`: + +```none +Usage: dtmt [OPTIONS] + +Commands: + build Build a project + bundle Manipulate the game's bundle files + dictionary Manipulate a hash dictionary file. + murmur Perform various operations on Murmur hashes. + new Create a new project + watch Re-build the given directory on file changes. + help Print this message or the help of the given subcommand(s) + +Options: + --dict Path to a dictionary file CSV format used to look up pre-computed murmur hashes. + Will default to `dictionary.csv` in the current directory. [default: dictionary.csv] + -h, --help Print help information + -V, --version Print version information +``` + +**Tip:** +Whenever a subcommand is expected, `help` can be given to produce the same output as including the `--help` flag. + +## Global Options + +| Flag | Value | Description | +|-------------------|-----------|--------------------------------------------------------------------------------------------------| +| `-h`, `--help` | | Prints help information about the current command. May also be specified in `[command_options]`. | +| `-V`, `--version` | | Prints version information. | +| `--dict` | file path | Sets the path to the Murmur hash dictionary. Defaults to `dictionary.csv`. May also be specified in `[command_options]`. + +## Subcommands + +### Build + +Builds the given mod project. + +> Not yet implemented. + +### Bundle + +A collection of commands to operate on data bundles. + +``` +$ dtmt bundle help +Usage: dtmt bundle [OPTIONS] + +Commands: + decompress Create a decompressed version of the given bundle(s). + This is mostly useful for staring at the decompressed data in a hex editor, + as neither the game nor this tool can read the decompressed bundles. + extract Extract files from the bundle(s). + inject Inject a file into a bundle. + list List the contents of one or multiple bundles. + help Print this message or the help of the given subcommand(s) + +Options: + --dict Path to a dictionary file CSV format used to look up pre-computed murmur hashes. + Will default to `dictionary.csv` in the current directory. [default: dictionary.csv] + --oodle The oodle library to load. This may either be: + - A library name that will be searched for in the system's default paths. + - A file path relative to the current working directory. + - An absolute file path. [default: liboo2corelinux64.so] + -h, --help Print help information +``` + +### Specifying bundle files + +Unless specified otherwise, all commands in this group can operate on multiple bundles at once. When the help output shows `bundle...` as a parameter, the command expects any number of file or directory paths. +File paths will be loaded a bundles regardless of their file name. Directories will be searched for files fitting Bitsquid's hashed bundle names (16 hex characters). + +Once all parameters have been resolved to bundle files, the operation is executed on all of them. + +Therefore, the content of all of the game's bundles can be listed at once, using: + +```shell +dtmt bundle list "\bundle" +``` + +#### Oodle Library + +The commands in this group require the Oodle compression library to work. A version compiled for Windows is shipped with the game (`binaries/oo2core_8_win64.dll`). For usage on Linux, see [Obtaining the Oodle library on Linux](Obtaining-the-Oodle-library-on-Linux). + +By default, DTMT will check the current working directory for the library compiled for the current operating system. However, you can use the `--oodle` flag to specify a custom name or path. + +- Specifying just a name (e.g. `--oodle different_lib.dll`) will search for that library in the system's default paths +- Specifying a relative or absolute file path will attempt to load that file as the library + + +#### Bundle Decompress + +``` +dtmt bundle decompress [OPTIONS] ... +``` + +Decompresses the raw byte stream of the bundle and writes it to a file with the rest of the bundle's metadata. +This is primarily intended for inspecting the bundle data manually, as neither the game nor this tool can otherwise use the decompressed file. + +#### Bundle Extract + +``` +dtmt bundle extract [OPTIONS] ... +``` + +Extracts files from the given bundle(s). + +| Flag | Value | Description | +|---------------------|-----------|---------------------------------------------------------------------------------------------------------------------------| +| `-i`, `--include` | file glob | Only extract files matching the given glob pattern. May be specified multiple times. | +| `-e`, `--exclude` | file glob | Do not extract files matching the given glob pattern. Takes precedence over `--include`. May be specified multiple times. | +| `-f`, `--flatten` | | Flatten the directory structure of the extracted files into the file name. | +| `-n`, `--dry-run` | | Simulate write operations and log what would have been done. | +| `-d`, `--decompile` | | Attempt to decompile files before writing. | +| `--ljd` | file path | Path to custom ljd executable | +| | | | + +#### Bundle Inject + +``` +dtmt bundle inject [OPTIONS] +``` + +Inject a file into a single bundle. Only one bundle can be specified. + +| Flag | Value | Description | +|-------------------|-----------|----------------------------------------------------------------------------------------| +| `-r`, `--replace` | name | Replace the named entry in the bundle with the contents of the given file. | +| `-o`, `--output` | file path | Path to write the changed bundle to. If omitted, the input bundle will be overwritten. | + +#### Bundle List + +``` +dtmt bundle list [OPTIONS] ... +``` + +Lists the contents of the given bundles. + +| Flag | Value | Description | +|----------|-------|----------------------------------------| +| `--json` | | Print output in machine-readable JSON. | diff --git a/cli_reference.adoc.md b/cli_reference.adoc.md deleted file mode 100644 index de21f4c..0000000 --- a/cli_reference.adoc.md +++ /dev/null @@ -1,9 +0,0 @@ -= CLI Reference -:toc: - -The general usage line is: - -[source,shell] ----- -dtmt [global_options] [command_options] [command_arguments] ----- \ No newline at end of file