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
batch_remote Dispatch a simulation to a remote target via MinIO staging.
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.
poll_batch Check the status of a dispatched batch job.
preprocess Preprocess geospatial data into JSHD format.
preprocess_batch Preprocess geospatial data on a remote target.
run Execute a simulation.
run_remote Execute a simulation on Josh Cloud.
stage_from_minio Download files from MinIO to a local directory.
stage_to_minio Upload a local directory to MinIO.
summarize_jfr Get a text summary of a JFR recording.
validate Validate a Josh script.

batch_remote

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

Dispatch a simulation to a remote target via MinIO staging.

Parameters

Name Type Description Default
config BatchRemoteConfig Batch remote configuration. required
timeout float | None Timeout in seconds. None
jfr JfrConfig | None Optional JFR profiling configuration. None
stream_output bool Stream JAR output to terminal in real time. False

Returns

Name Type Description
CLIResult CLIResult with execution details.

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.

poll_batch

cli.JoshCLI.poll_batch(config, timeout=None)

Check the status of a dispatched batch job.

Exit codes

0 — complete (job succeeded, stdout has JSON status) 1 — error (job failed, stdout has JSON with error details) 2 — running / pending 100 — poll failure (transient error, caller should retry)

Parameters

Name Type Description Default
config PollBatchConfig Poll-batch configuration with job_id and target. required
timeout float | None Timeout in seconds. None

Returns

Name Type Description
CLIResult CLIResult with exit_code indicating job state.

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.

preprocess_batch

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

Preprocess geospatial data on a remote target.

Parameters

Name Type Description Default
config PreprocessBatchConfig Preprocess-batch 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.

stage_from_minio

cli.JoshCLI.stage_from_minio(config, timeout=None)

Download files from MinIO to a local directory.

Parameters

Name Type Description Default
config StageFromMinioConfig Stage-from-MinIO configuration. required
timeout float | None Timeout in seconds. None

Returns

Name Type Description
CLIResult CLIResult with execution details.

stage_to_minio

cli.JoshCLI.stage_to_minio(config, timeout=None)

Upload a local directory to MinIO.

Parameters

Name Type Description Default
config StageToMinioConfig Stage-to-MinIO configuration. required
timeout float | None Timeout in seconds. None

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.