cli.JoshCLI

cli.JoshCLI(
    josh_jar=None,
    java_path='java',
    auto_download=True,
    working_dir=None,
    jar_dir=None,
)

Executes Josh CLI commands via subprocess.

This is a thin wrapper that builds command lines and runs them. No business logic - just CLI invocation.

Supports three jar modes: - Path: Use a specific jar file - JarMode.PROD: Use production jar from joshsim.org (default) - JarMode.DEV: Use development jar from joshsim.org - JarMode.LOCAL: Use local jar from jar/joshsim-fat.jar

Attributes

Name Type Description
josh_jar Path | JarMode | None Path to jar, JarMode enum, or None for default (PROD).
java_path str Path to java executable.
auto_download bool If True, download jars automatically if needed.
working_dir Path | None Working directory for command execution.

Examples

>>> cli = JoshCLI(josh_jar=Path("joshsim-fat.jar"))
>>> # Run a simulation
>>> result = cli.run(RunConfig(
...     script=Path("sim.josh"),
...     simulation="Main",
...     replicates=5,
... ))
>>> # Preprocess data
>>> result = cli.preprocess(PreprocessConfig(
...     script=Path("sim.josh"),
...     simulation="Main",
...     data_file=Path("temp.nc"),
...     variable="temperature",
...     units="K",
...     output=Path("temp.jshd"),
... ))

Methods

Name Description
diagnose_jfr Parse a JFR recording into user-friendly resource diagnostics.
discover_config Discover configuration variables in a Josh script.
inspect_exports Inspect export paths in a Josh script.
inspect_jshd Inspect values in a JSHD file.
preprocess Preprocess geospatial data into JSHD format.
run Execute a simulation.
run_remote Execute a simulation on Josh Cloud.
summarize_jfr Get a text summary of a JFR recording.
validate Validate a Josh script.

diagnose_jfr

cli.JoshCLI.diagnose_jfr(jfr_path, timeout=None)

Parse a JFR recording into user-friendly resource diagnostics.

Runs jfr print and jfr summary to extract CPU, memory, GC, I/O, and thread contention metrics, then classifies the likely bottleneck.

Parameters

Name Type Description Default
jfr_path Path Path to the .jfr recording file. required
timeout float | None Timeout in seconds for each jfr subprocess call. None

Returns

Name Type Description
'ResourceProfile' class:~joshpy.jfr.ResourceProfile with parsed diagnostics.

Raises

Name Type Description
RuntimeError If jfr commands fail.

discover_config

cli.JoshCLI.discover_config(config, timeout=None, jfr=None)

Discover configuration variables in a Josh script.

Parameters

Name Type Description Default
config DiscoverConfigConfig Discover config configuration. required
timeout float | None Timeout in seconds. None
jfr JfrConfig | None Optional JFR profiling configuration. None

Returns

Name Type Description
CLIResult CLIResult with execution details.

inspect_exports

cli.JoshCLI.inspect_exports(config, timeout=None, jfr=None)

Inspect export paths in a Josh script.

Parameters

Name Type Description Default
config InspectExportsConfig Inspect exports configuration. required
timeout float | None Timeout in seconds. None
jfr JfrConfig | None Optional JFR profiling configuration. None

Returns

Name Type Description
ExportPaths ExportPaths with parsed export file information.

Raises

Name Type Description
RuntimeError If command fails (includes exit code context).

inspect_jshd

cli.JoshCLI.inspect_jshd(config, timeout=None, jfr=None)

Inspect values in a JSHD file.

Parameters

Name Type Description Default
config InspectJshdConfig Inspect JSHD configuration. required
timeout float | None Timeout in seconds. None
jfr JfrConfig | None Optional JFR profiling configuration. None

Returns

Name Type Description
CLIResult CLIResult with execution details.

preprocess

cli.JoshCLI.preprocess(config, timeout=None, jfr=None)

Preprocess geospatial data into JSHD format.

Supports NetCDF, GeoTIFF/COG, and CSV input formats. Use the appropriate config class for your input format:

  • NetcdfPreprocessConfig: For .nc files with time dimensions
  • GeotiffPreprocessConfig: For .tif/.tiff/COG rasters
  • CsvPreprocessConfig: For .csv point data

Parameters

Name Type Description Default
config PreprocessConfig Format-specific preprocess configuration. required
timeout float | None Timeout in seconds. None
jfr JfrConfig | None Optional JFR profiling configuration. None

Returns

Name Type Description
CLIResult CLIResult with execution details.

run

cli.JoshCLI.run(config, timeout=None, jfr=None, stream_output=False)

Execute a simulation.

Parameters

Name Type Description Default
config RunConfig Run configuration. required
timeout float | None Timeout in seconds. None
jfr JfrConfig | None Optional JFR profiling configuration. None
stream_output bool If True, stream JAR stdout/stderr to the terminal in real time while still capturing them. False

Returns

Name Type Description
CLIResult CLIResult with execution details.

run_remote

cli.JoshCLI.run_remote(config, timeout=None, jfr=None, stream_output=False)

Execute a simulation on Josh Cloud.

Parameters

Name Type Description Default
config RunRemoteConfig Run remote configuration. required
timeout float | None Timeout in seconds. None
jfr JfrConfig | None Optional JFR profiling configuration. None
stream_output bool If True, stream JAR stdout/stderr to the terminal in real time while still capturing them. False

Returns

Name Type Description
CLIResult CLIResult with execution details.

summarize_jfr

cli.JoshCLI.summarize_jfr(jfr_path, timeout=None)

Get a text summary of a JFR recording.

Uses the jfr CLI tool bundled with the JDK to produce a human-readable summary of a flight recording. Users can paste this into GitHub issues without needing JDK Mission Control or IntelliJ.

The jfr binary is resolved relative to :attr:java_path: if java_path points into a JDK bin/ directory, the sibling jfr binary is used; otherwise jfr is expected to be on PATH.

Parameters

Name Type Description Default
jfr_path Path Path to the .jfr recording file. required
timeout float | None Timeout in seconds. None

Returns

Name Type Description
CLIResult CLIResult where stdout contains the text summary.

validate

cli.JoshCLI.validate(config, timeout=None, jfr=None)

Validate a Josh script.

Parameters

Name Type Description Default
config ValidateConfig Validate configuration. required
timeout float | None Timeout in seconds. None
jfr JfrConfig | None Optional JFR profiling configuration. None

Returns

Name Type Description
CLIResult CLIResult with execution details.