CLI Reference

Usage

jgo [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGS]

If the first argument contains a colon (:), jgo treats it as an endpoint and implicitly runs jgo run:

# These are equivalent:
jgo org.python:jython-standalone
jgo run org.python:jython-standalone

Global Options

These options apply to all commands and must appear before the command name:

Output control

Option

Description

-v, --verbose

Verbose output. Repeat for more detail: -vv (debug), -vvv (trace).

-q, --quiet

Suppress all output.

--color {auto,rich,styled,plain}

Control output formatting. auto detects TTY. Aliases: always=rich, never=plain. Env: COLOR.

--wrap {auto,smart,raw}

Control line wrapping. auto uses smart wrapping for TTYs, raw for pipes.

--dry-run

Show what would be done without doing it. Dependencies may still be downloaded to report accurate information.

Environment and cache

Option

Description

-f, --file FILE

Use a specific jgo.toml file (default: jgo.toml in current directory).

--cache-dir PATH

Override cache directory. Env: JGO_CACHE_DIR.

--repo-cache PATH

Override Maven repository cache. Env: M2_REPO.

--no-cache

Skip cache entirely, always rebuild. Env: JGO_NO_CACHE.

-u, --update

Update cached environment (checks remote repositories). Env: JGO_UPDATE.

--offline

Work offline – don’t download anything. Env: JGO_OFFLINE.

Resolver and dependencies

Option

Description

--resolver {auto,python,mvn}

Dependency resolver. auto (default) tries pure Python first, falls back to Maven.

-r, --repository NAME:URL

Add a remote Maven repository. Can be repeated.

--links {hard,soft,copy,auto}

How to link JARs from Maven cache to environment. Default: from config or auto.

--include-optional

Include optional dependencies. Env: JGO_INCLUDE_OPTIONAL.

--lenient

Warn instead of failing on unresolved dependencies. Env: JGO_LENIENT.

--full-coordinates

Include default coordinate components (jar packaging, compile scope) in output.

Java

Option

Description

--java-version VERSION

Force a specific Java version (e.g., 17). Env: JAVA_VERSION.

--java-vendor VENDOR

Prefer a specific Java vendor (e.g., adoptium, zulu).

--system-java

Use system Java instead of downloading on demand.

--min-heap SIZE

Minimum/initial heap size (e.g., 512M, 1G).

--max-heap SIZE

Maximum heap size (e.g., 4G). Overrides auto-detection.

--gc FLAG

GC options. Shorthand: --gc=G1, --gc=Z. Special: auto, none. Can be repeated.

Advanced

Option

Description

-D KEY=VALUE, --property KEY=VALUE

Set property for Maven profile activation.

--platform PLATFORM

Target platform for profile activation. Sets os-name, os-family, and os-arch.

--os-name NAME

OS name for profile activation (e.g., Linux, Windows).

--os-family FAMILY

OS family for profile activation (e.g., unix, windows).

--os-arch ARCH

OS architecture for profile activation (e.g., amd64, aarch64).

--os-version VERSION

OS version for profile activation.

--module-path-only

Force all JARs to module-path (treat as modular).

--class-path-only

Force all JARs to classpath (disable module detection).

--ignore-config

Ignore the ~/.config/jgo.conf settings file.

Commands

jgo run

Run a Java application from Maven coordinates or jgo.toml.

jgo run [OPTIONS] [ENDPOINT] [-- JVM_ARGS] [-- APP_ARGS]

Option

Description

--main-class CLASS

Main class to run. Supports auto-completion for simple names.

--entrypoint NAME

Run a specific entrypoint from jgo.toml.

--add-classpath PATH

Append JARs, directories, or other paths to the classpath. Can be repeated.

Argument separators: Use -- to separate JVM arguments and application arguments:

# No extra args
jgo run org.python:jython-standalone

# JVM args only
jgo run org.python:jython-standalone -- -Xmx4G

# JVM args and app args
jgo run org.python:jython-standalone -- -Xmx4G -- script.py --verbose

# App args only (empty JVM section)
jgo run org.python:jython-standalone -- -- script.py

If no endpoint is given and a jgo.toml exists in the current directory, jgo runs its default entrypoint.

jgo init

Create a new jgo.toml environment file.

jgo init [OPTIONS] [ENDPOINT]

Option

Description

-r, --requirements FILE

Add coordinates from a requirements file (one per line, # for comments).

 
# Create empty jgo.toml
jgo init

# Initialize with a dependency
jgo init org.python:jython-standalone:2.7.3

# Initialize with multiple dependencies from a file
jgo init -r requirements.txt

jgo add

Add dependencies to jgo.toml.

jgo add [OPTIONS] [COORDINATES...]

Option

Description

-r, --requirements FILE

Read coordinates from a requirements file.

--no-sync

Don’t automatically sync after adding.

 
jgo add org.slf4j:slf4j-simple:2.0.9
jgo add org.scijava:scijava-common org.scijava:scripting-jython

jgo remove

Remove dependencies from jgo.toml.

jgo remove [OPTIONS] COORDINATES...

Option

Description

--no-sync

Don’t automatically sync after removing.

 
jgo remove org.slf4j:slf4j-simple

jgo sync

Resolve dependencies and build the environment in .jgo/.

jgo sync [OPTIONS]

Option

Description

--force

Force rebuild even if cached.

jgo update

Update dependencies to latest versions within constraints. Equivalent to jgo sync --update.

jgo update [OPTIONS]

Option

Description

--force

Force rebuild even if cached.

jgo lock

Update jgo.lock.toml without building the environment.

jgo lock [OPTIONS]

Option

Description

--check

Check if lock file is up to date (exits non-zero if stale).

jgo list

List resolved dependencies as a flat list.

jgo list [OPTIONS] [ENDPOINT]

Option

Description

--direct

Show only direct (non-transitive) dependencies.

Without an endpoint, operates on the jgo.toml in the current directory.

jgo tree

Show the dependency tree.

jgo tree [OPTIONS] [ENDPOINT]

Without an endpoint, operates on the jgo.toml in the current directory.

jgo info

Show information about an environment or artifact. This is a command group with subcommands:

jgo info classpath [ENDPOINT]       # Show classpath
jgo info modulepath [ENDPOINT]      # Show module-path
jgo info jars [ENDPOINT]            # Show all JAR paths (classpath + module-path)
jgo info deptree [ENDPOINT]         # Show dependency tree
jgo info deplist [ENDPOINT]         # Show flat dependency list
jgo info javainfo [ENDPOINT]        # Show Java version requirements
jgo info entrypoints                # Show entrypoints from jgo.toml
jgo info versions COORDINATE       # List available versions of an artifact
jgo info mains [ENDPOINT]           # Show classes with public main methods
jgo info manifest [ENDPOINT]        # Show JAR manifest
jgo info pom [ENDPOINT]             # Show POM content
jgo info envdir [ENDPOINT]          # Show environment directory path

jgo config

Manage jgo configuration.

jgo config list                          # List all configuration values
jgo config get KEY                       # Get a configuration value
jgo config set KEY VALUE                 # Set a configuration value
jgo config unset KEY                     # Remove a configuration value
jgo config shortcut                      # List all shortcuts
jgo config shortcut NAME                 # Show what a shortcut expands to
jgo config shortcut NAME ENDPOINT        # Add or update a shortcut
jgo config shortcut --remove NAME        # Remove a shortcut

jgo version

Display jgo’s version.

jgo version
jgo --version   # Also works as a global flag

Endpoint format

Endpoints are the coordinate strings that identify what to run or inspect:

groupId:artifactId[:version][:classifier][@mainClass]

Use + to combine multiple artifacts: g:a+g2:a2@MainClass.

Coordinate modifiers

Append parenthesized modifiers to control placement and resolution:

Modifier

Meaning

(c) or (cp)

Force onto classpath

(m) or (mp)

Force onto module-path

!

Disable dependency management (BOM import) for this coordinate

Modifiers can be combined: g:a:v(m)!

# Force a JAR onto the module-path
jgo org.lwjgl:lwjgl:3.3.1(m)

# Disable managed resolution for one coordinate
jgo org.scijava:scijava-common!

Explicit positioning

When jgo’s heuristic parsing (which guesses whether a field is a version, classifier, or packaging) gets it wrong, use consecutive colons to set fields by position:

groupId:artifactId:version:classifier:packaging:scope

Empty positions default to None:

g:a:1.0:       # version=1.0, classifier=None (explicit)
g:a::sources   # version=None, classifier=sources (explicit)

Examples

Basic usage

# Run Jython REPL
jgo org.python:jython-standalone

# Run JRuby
echo "puts 'Hello Ruby'" | jgo org.jruby:jruby-complete@jruby.Main

# Run Groovy shell
jgo org.codehaus.groovy:groovy-groovysh+commons-cli:commons-cli:1.3.1@shell.Main

With the SciJava repository

Add the SciJava repository to your configuration:

[repositories]
scijava.public = https://maven.scijava.org/content/groups/public

Then run SciJava tools:

# SciJava REPL with different scripting languages
jgo org.scijava:scijava-common+org.scijava:scripting-jython@ScriptREPL
jgo org.scijava:scijava-common+org.scijava:scripting-groovy@ScriptREPL

Inspecting artifacts

# Preview the java command without running
jgo --dry-run run org.scijava:parsington

# Preview what jgo init would create
jgo --dry-run init org.python:jython-standalone

# Check available versions
jgo info versions org.python:jython-standalone

# Show main classes in a JAR
jgo info mains org.scijava:parsington

Working with Java versions

# Use a specific Java version
jgo --java-version 17 net.imagej:imagej

# Use system Java instead of downloading
jgo --system-java org.python:jython-standalone

# Check what Java version is needed
jgo info javainfo net.imagej:imagej