Other ways to run the CLI

• Use JBang
• Use Homebrew
  • Use pre-built platform binary
• Use Java to run the jar
• Build and run from source
• Using unreleased snapshots

JBang is a tool designed to simplify Java application execution. By eliminating the need for traditional build tools and app servers, JBang enables quick and easy running of Java apps, scripts, and more.

1. Install JBang: https://www.jbang.dev/documentation/jbang/latest/installation.html

2. Install the pre-built release of ttrpg-convert-cli:

   jbang app install --name ttrpg-convert --force --fresh https://github.com/ebullient/ttrpg-convert-cli/releases/download/3.3.1/ttrpg-convert-cli-3.3.1-runner.jar
   

   🚧 If you want the latest unreleased snapshot:

   jbang app install --name ttrpg-convert --force --fresh https://github.com/ebullient/ttrpg-convert-cli/releases/download/299-SNAPSHOT/ttrpg-convert-cli-299-SNAPSHOT-runner.jar
   

   🔹 Feel free to use an alternate alias by replacing the value specified as the name. For example, for the snapshot, you can use --name ttrpg-convert-ss, allowing you to keep both versions available. You will need to adjust commands accordingly.

3. Verify the install by running the command:

   ttrpg-convert --help
   

   Notice there is no leading ./ or .\. JBang installs the command in a location that is on your PATH^[1].

Next steps:

• Understand CLI plugin and usage conventions.
• Convert 5eTools JSON data
• Convert PF2eTools JSON data
• Convert Homebrew JSON data
• Create your own configuration file.

Not to be confused with Homebrew adventures, Homebrew is a package manager for Mac OS (and sometimes linux).

1. Install Homebrew: https://brew.sh/

2. Install the tap:

   brew tap ebullient/tap
   

3. Install the cli:

   brew install ttrpg-convert-cli
   

4. Verify the install by running the command (from anywhere):

   ttrpg-convert --help
   

   Notice there is no leading ./ or .\. Homebrew installs the command in a location that is on your PATH^[1:1].

Next steps:

• Understand CLI plugin and usage conventions.
• Convert 5eTools JSON data
• Convert PF2eTools JSON data
• Convert Homebrew JSON data
• Create your own configuration file.

Download the latest release of the zip or tgz for your platform. Extract the archive. A ttrpg-convert binary executable will be in the extracted bin directory.

In a terminal or command shell, navigate to the directory where you extracted the archive and run the command in the bin directory:

# Linux or MacOS (use the leading ./ because the current directory is not in the PATH[^1])
./ttrpg-convert --help

# Windows (the .exe extension is optional)
ttrpg-convert.exe --help

Notes:

• Windows users: the .exe extension is optional. You can run ttrpg-convert.exe or ttrpg-convert interchangeably.
• Folks familar with command line tools can add the bin directory to their path to make the command available from anywhere.
• MacOS permission checking (unverified executable): xattr -r -d com.apple.quarantine <path/to>/ttrpg-convert

Next steps:

• Understand CLI plugin and usage conventions.
• Convert 5eTools JSON data
• Convert PF2eTools JSON data
• Convert Homebrew JSON data
• Create your own configuration file.

To run the CLI, you will need to have Java 17 installed on your system.

1. Ensure you have Java 17 installed on your system and active in your path.

2. Download the CLI as a jar

   • Latest release: ttrpg-convert-cli-3.3.1-runner.jar
   • 🚧 unreleased snapshot: ttrpg-convert-cli-399-SNAPSHOT-runner.jar

3. Verify the install by running the command:

   java -jar ttrpg-convert-cli-3.3.1-runner.jar --help
   

   🚧 If you are using the unreleased snapshot, use the following command:

   java -jar ttrpg-convert-cli-299-SNAPSHOT-runner.jar --help
   

To run commands, replace ttrpg-convert with java -jar ttrpg-convert-cli-...

Next steps:

• Understand CLI plugin and usage conventions.
• Convert 5eTools JSON data
• Convert PF2eTools JSON data
• Convert Homebrew JSON data
• Create your own configuration file.

This is a Quarkus project that uses Maven as its build tool.

• You can use the Quarkus CLI to build and run the project
• You can use Maven to build and run the project via the maven wrapper (the mvnw script). The Maven Wrapper is a tool that provides a standardized way to execute Maven builds, ensuring the correct version and configurations are used.

1. Clone this repository

2. Ensure you have Java 17 installed on your system and active in your path.

3. Build this project:

   • Build with the Quarkus CLI: quarkus build
   • Build with the Maven wrapper: ./mvnw install

4. Verify the build: java -jar target/ttrpg-convert-cli-299-SNAPSHOT-runner.jar --help

To run commands, either:

• Replace ttrpg-convert with java -jar target/ttrpg-convert-cli-299-SNAPSHOT-runner.jar, or

• Use JBang to create an alias that points to the built jar:

  jbang app install --name ttrpg-convert --force --fresh ~/.m2/repository/dev/ebullient/ttrpg-convert-cli/299-SNAPSHOT/ttrpg-convert-cli-299-SNAPSHOT-runner.jar
  

  🔹 Use an alternate alias by replacing the value specified as the name: --name ttrpg-convert, and adjust the commands accordingly.

Next steps:

• Understand CLI plugin and usage conventions.
• Convert 5eTools JSON data
• Convert PF2eTools JSON data
• Convert Homebrew JSON data
• Create your own configuration file.

Folks picking up early snapshots is really helpful for me, but using an unreleased snapshot may be unstable.

• Build from source

• Use JBang to install the snapshot

• 🚧 Do not run an unstable CLI directly against notes in your Obsidian vault

• 👷‍♀️ Be prepared to report issues if you find them.

  • Be as specific as you can about the configuration and sources that are not working.
  • ttrpg-convert --version will tell you the version you are running, including the commit! Please include that information in your report.

I recommend staying with official releases unless you are willing to help me debug issues (and your help is very much appreciated!).