DBOS CLI (#201)

Note, `init` command will come in a later PR

---------

Co-authored-by: chuck-dbos <134347445+chuck-dbos@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

transact-cli/README.md

@@ -0,0 +1,187 @@
+# DBOS CLI
+
+The DBOS CLI is a command-line interface for managing DBOS workflows.
+
+## Installation
+
+DBOS CLI is distributed as a JAR with dependencies (also known as a fat or uber JAR).
+It is run from the command line with the `-jar` option of the [`java` command](https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html).
+
+```shell
+$ java -jar dbos.jar --version
+dbos v0.7.0
+```
+
+## Configuration
+
+### Database Connection Configuration
+
+Many of the DBOS CLI commands require a DBOS system database connection to operate.
+The DBOS system database connection is specified via a JDBC URL plus a username and password.
+These values can be specified on the command line or via environment variables.
+
+* System Database JDBC URL
+  * `--db-url` / `-D` flag
+  * `DBOS_SYSTEM_JDBC_URL` environment variable
+* System Database user
+  * `--db-user` / `-U` flag
+  * `PGUSER` environment variable
+* System Database password
+  * `--db-password` / `-P` flag
+  * `PGPASSWORD` environment variable
+
+Example:
+```bash
+# Using command-line flag (highest priority)
+java -jar dbos.jar migrate --db-url jdbc:postgresql://localhost/mydb -U user -P password
+
+# Using environment variable (lowest priority)
+export DBOS_SYSTEM_JDBC_URL=jdbc:postgresql://localhost/mydb
+export PGUSER=user
+export PGPASSWORD=password
+java -jar dbos.jar migrate
+```
+
+### `dbos migrate`
+Create DBOS system tables in your database. This command runs the migration commands specified in the `database.migrate` section of your config file.
+
+**Options:**
+- `-r, --app-role <role>` - The role with which you will run your DBOS application
+
+**Usage:**
+```bash
+java -jar dbos.jar migrate
+java -jar dbos.jar migrate --app-role myapp_role
+```
+
+### `dbos reset`
+Reset the DBOS system database, deleting metadata about past workflows and steps. _This is a permanent, destructive action!_
+
+**Options:**
+- `-y, --yes` - Skip confirmation prompt
+
+**Usage:**
+```bash
+java -jar dbos.jar reset
+java -jar dbos.jar reset --yes  # Skip confirmation
+```
+
+### `dbos postgres`
+Manage a local PostgreSQL database with Docker for development.
+
+#### `dbos postgres start`
+Start a local Postgres database container with pgvector extension.
+
+**Options:**
+- `-c, --container-name` - Docker container name, defaults to dbos-db
+- `-i, --image-name` - Docker image name, defaults to pgvector/pgvector:pg16
+
+**Usage:**
+```bash
+java -jar dbos.jar postgres start
+```
+
+Creates a PostgreSQL container with:
+- Container name: `dbos-db` (unless overridden by `--container-name`)
+- Port: 5432
+- Default database: `dbos`
+- Default user: `postgres`
+- Default password: `dbos`
+
+#### `dbos postgres stop`
+Stop the local Postgres database container.
+
+**Usage:**
+```bash
+java -jar dbos.jar postgres stop
+```
+**Options:**
+- `-c, --container-name` - Docker container name, defaults to dbos-db
+
+### `dbos workflow`
+Manage DBOS workflows.
+
+#### `dbos workflow list`
+List workflows for your application.
+
+**Options:**
+- `-l, --limit <number>` - Limit the results returned (default: 10)
+- `-o, --offset <number>` - Offset for pagination
+- `-S, --status <status>` - Filter by status (PENDING, SUCCESS, ERROR, ENQUEUED, CANCELLED, or MAX_RECOVERY_ATTEMPTS_EXCEEDED)
+- `-n, --name <name>` - Retrieve workflows with this name
+- `-v, --application-version <version>` - Retrieve workflows with this application version
+- `-s, --start-time <timestamp>` - Retrieve workflows starting after this timestamp (ISO 8601)
+- `-e, --end-time <timestamp>` - Retrieve workflows starting before this timestamp (ISO 8601)
+- `-q, --queue <queue>` - Retrieve workflows on this queue
+- `-Q, --queues-only` - Retrieve only queued workflows
+- `-d, --sort-desc` - Sort the results in descending order (older first)
+
+**Usage:**
+```bash
+java -jar dbos.jar workflow list
+java -jar dbos.jar workflow list --limit 50 --status SUCCESS
+java -jar dbos.jar workflow list --name "ProcessOrder"
+```
+
+#### `dbos workflow get [workflow-id]`
+Retrieve the status of a specific workflow.
+
+**Usage:**
+```bash
+java -jar dbos.jar workflow get abc123def456
+```
+
+Returns detailed information about the workflow including its status, start time, end time, and other metadata.
+
+#### `dbos workflow steps [workflow-id]`
+List the steps of a workflow.
+
+**Usage:**
+```bash
+java -jar dbos.jar workflow steps abc123def456
+```
+
+Shows all the steps executed within a workflow, their status, and execution details.
+
+#### `dbos workflow cancel [workflow-id]`
+Cancel a workflow so it is no longer automatically retried or restarted.
+
+**Usage:**
+```bash
+java -jar dbos.jar workflow cancel abc123def456
+```
+
+#### `dbos workflow resume [workflow-id]`
+Resume a workflow that has been cancelled.
+
+**Usage:**
+```bash
+java -jar dbos.jar workflow resume abc123def456
+```
+
+#### `dbos workflow fork [workflow-id]`
+Fork a workflow from the beginning or from a specific step.
+
+**Options:**
+- `-s, --step <number>` - Restart from this step (default: 1)
+- `-f, --forked-workflow-id <id>` - Custom workflow ID for the forked workflow
+- `-a, --application-version <version>` - Application version for the forked workflow
+
+**Usage:**
+```bash
+java -jar dbos.jar workflow fork abc123def456
+java -jar dbos.jar workflow fork abc123def456 --step 3
+java -jar dbos.jar workflow fork abc123def456 --forked-workflow-id custom-id-123
+```
+
+### `dbos version`
+Show the version and exit.
+
+**Usage:**
+```bash
+java -jar dbos.jar --version
+```
+
+## License
+
+See the main project [LICENSE](https://github.com/dbos-inc/dbos-transact-java/blob/main/LICENSE) file for details.

transact-cli/build.gradle.kts

@@ -1,5 +1,6 @@
 plugins {
     application
+    id("com.gradleup.shadow") version "9.2.2"
 }
 
 application {
@@ -8,4 +9,43 @@ application {
 
 dependencies {
     implementation(project(":transact"))
+    implementation("com.fasterxml.jackson.core:jackson-databind:2.17.0") // json
+    implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.17.0")
+    implementation("info.picocli:picocli:4.7.7")
+    runtimeOnly("org.slf4j:slf4j-simple:2.0.13")
+
+    testImplementation(platform("org.junit:junit-bom:5.12.1"))
+    testImplementation("org.junit.jupiter:junit-jupiter")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+tasks.test {
+    useJUnitPlatform()
+    testLogging {
+        events("passed", "skipped", "failed")
+        showStandardStreams = true
+
+        afterSuite(KotlinClosure2({ desc: TestDescriptor, result: TestResult ->
+            if (desc.parent == null) {
+                println("\nTest Results:")
+                println("  Tests run: ${result.testCount}")
+                println("  Passed: ${result.successfulTestCount}")
+                println("  Failed: ${result.failedTestCount}")
+                println("  Skipped: ${result.skippedTestCount}")
+            }
+        }))
+    }
+}
+
+tasks.named<com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar>("shadowJar") {
+    archiveBaseName.set("dbos")
+    archiveVersion.set("")
+    archiveClassifier.set("")
+}
+
+tasks.withType<JavaCompile> {
+    options.compilerArgs.add("-Xlint:unchecked")    // warn about unchecked operations
+    options.compilerArgs.add("-Xlint:deprecation")  // warn about deprecated APIs
+    options.compilerArgs.add("-Xlint:rawtypes")     // warn about raw types
+    options.compilerArgs.add("-Werror")             // treat all warnings as errors
 }

transact-cli/src/main/java/dev/dbos/transact/cli/DBOSCommand.java

@@ -0,0 +1,38 @@
+package dev.dbos.transact.cli;
+
+import dev.dbos.transact.DBOS;
+
+import java.util.Objects;
+
+import picocli.CommandLine;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.IVersionProvider;
+
+@Command(
+    name = "dbos",
+    description = "DBOS CLI is a command-line interface for managing DBOS workflows",
+    mixinStandardHelpOptions = true,
+    subcommands = {
+      MigrateCommand.class,
+      PostgresCommand.class,
+      ResetCommand.class,
+      WorkflowCommand.class
+    },
+    versionProvider = DBOSCommand.class)
+public class DBOSCommand implements Runnable, IVersionProvider {
+
+  @Override
+  public void run() {
+    CommandLine cmd = new CommandLine(this);
+    cmd.usage(System.out);
+  }
+
+  @Override
+  public String[] getVersion() throws Exception {
+    var pkg = DBOS.class.getPackage();
+    var ver = pkg == null ? null : "v%s".formatted(pkg.getImplementationVersion());
+    return new String[] {
+      "${COMMAND-FULL-NAME} " + Objects.requireNonNullElse(ver, "<unknown version>")
+    };
+  }
+}

transact-cli/src/main/java/dev/dbos/transact/cli/DatabaseOptions.java

@@ -0,0 +1,43 @@
+package dev.dbos.transact.cli;
+
+import dev.dbos.transact.DBOSClient;
+
+import picocli.CommandLine.Option;
+
+public class DatabaseOptions {
+  @Option(
+      names = {"-D", "--db-url"},
+      defaultValue = "${DBOS_SYSTEM_JDBC_URL}",
+      description = "Your DBOS system database URL [default: DBOS_SYSTEM_JDBC_URL env var]")
+  private String url;
+
+  @Option(
+      names = {"-U", "--db-user"},
+      defaultValue = "${PGUSER}",
+      description = "user name for your DBOS system database [default: PGUSER env var]")
+  private String user;
+
+  @Option(
+      names = {"-P", "--db-password"},
+      defaultValue = "${PGPASSWORD}",
+      description = "password for your DBOS system database [default: PGPASSWORD env var]",
+      arity = "0..1",
+      interactive = true)
+  private String password;
+
+  public String url() {
+    return this.url;
+  }
+
+  public String user() {
+    return this.user;
+  }
+
+  public String password() {
+    return this.password;
+  }
+
+  public DBOSClient createClient() {
+    return new DBOSClient(url(), user(), password());
+  }
+}

transact-cli/src/main/java/dev/dbos/transact/cli/Main.java

@@ -1,7 +1,11 @@
 package dev.dbos.transact.cli;
 
+import picocli.CommandLine;
+
 public class Main {
   public static void main(String[] args) {
-    System.out.println("Hello World");
+    var cmd = new CommandLine(new DBOSCommand());
+    var exitCode = cmd.execute(args);
+    System.exit(exitCode);
   }
 }