jdx command reference

The user-facing catalogue. Every shipped flag must appear in jdx <command> --help, here, and in docs/PROPOSAL.md Appendix B. (Moved out of README.md to keep it a hook, demo, install, quickstart, and links.)

jdx <command> --help documents each command; jdx help --agent prints the compact agent block. Every query command accepts --json (same information, structured envelope) and --no-daemon (force in-process even when the daemon is up).

Read: declaration, members, structure#

body/source ladder: paired sources → Vineflower reconstruction → javap disassembly → signatures → not found. --engine vineflower forces reconstruction even when sources are paired; --engine javap shows raw bytecode. Decompiled output is always labelled ⚠ reconstructed with the engine named.

Search and browse#

Graph: usages, hierarchy, calls, samples#

Upgrades: API diff#

$ jdx diff gson-2.11.0.jar gson-2.14.0.jar --fail-on breaking
api diff gson-2.11.0.jar -> gson-2.14.0.jar (public surface)
info  FIELD_CONSTANT_VALUE_CHANGED  com.google.gson.internal.GsonBuildConfig#VERSION: "2.11.0" -> "2.14.0"
0 breaking · 0 suspicious · 17 informational · 2 types added · 0 types removed
fail-on breaking: no breaking changes (exit 0)
source: gson-2.11.0.jar (bytecode)
source: gson-2.14.0.jar (bytecode)
next: jdx members com.google.gson.internal.GsonBuildConfig

diff exits 0 whenever the comparison ran, whatever it found — the answer is in the report, not in the process status. --fail-on breaking (or any) is the CI gate and is the only way a successful diff exits non-zero (see the exit-code table). It needs no workspace, no --jars and no --no-daemon, and is answered by the MCP tool jdx_diff and GET /v1/diff?query=<old>&new=<new> with identical bytes.

Environment and maintenance#

Serving: daemon, MCP, HTTP, batch#

Classpath flags (every query command)#

--jars <jar|dir|glob> (repeatable, merged in front of the workspace; quote globs so the shell does not expand them — an unquoted multi-path expansion exits 3 with a hint) · --coord group:artifact:version (repeatable; local ~/.gradle/caches + ~/.m2 first) · --repo <url> (repeatable Maven mirror, tried before Central) · --fetch (allow downloads incl. -sources.jar, checksum-verified into <cache-dir>/m2/ (~/.cache/jdx/m2/ on Linux)) · --no-jdk (exclude the running JDK stdlib, included by default via jrt:/ + src.zip) · -w/--workspace <name> (also JDX_WORKSPACE env or jdx ws use default; Gradle/Maven project roots auto-discover from the working directory) · --src <dir> (only usages, batch, bench, and ws create: source dirs scanned textually).

Global output flags: --json (accepted before or after the subcommand, e.g. jdx --json show …), --no-color (piped output is always plain), --no-daemon (force in-process). The daemon wire always carries plain text (no TTY); the CLI re-colorizes warm text locally on a TTY with the same --no-color / console gate as cold, so piped warm stays byte-identical to piped cold (issue #17). --json bytes are identical cold and warm.

Exit codes and symbol references#

The one exception is jdx diff's --fail-on breaking\|any gate, which exits 1 when it trips: a successful comparison otherwise always exits 0, and the verdict is in the envelope as result.gate too.

References are Javadoc style — com.example.Outer, com.example.Outer#method(Type), short Outer#method (resolved, or exit 2 with candidates). Always quote the ref: # and ( are shell-hostile. :: and . are accepted in place of #. Constructors are <init>, static initialisers <clinit>.

Every --json answer uses one envelope: {"jdx":1, "ok":…, "command":…, "query":…, "result":…, "truncated":…, "warnings":…, "provenance":…}. Warnings carry stable codes (DUPLICATE_FQN, CORRUPT_CLASS, SOURCES_VERSION_MISMATCH, …); provenance names the artifact, the source (sources / bytecode / decompiled + engine), and the file:lines.

Kotlin note#

Kotlin signatures come from @Metadata (suspend, properties, default args, @JvmName); Kotlin member bodies and KDoc come from .kt sources through a side-loaded kotlin-compiler-embeddable (never on the compile classpath, never in the fat jar). Without the sidecar, body/source/doc over .kt-only roots degrade to decompile/javap — they emit something and say what it is, never an error. Run jdx kotlin install to fetch the sidecar set (SHA-1 checked) from Maven Central; jdx doctor reports its status. File facades and multi-file parts project through KmPackage the same way classes use KmClass (suspend, properties, @JvmName); a multi-file facade umbrella merges its parts when the jar is open. Corrupt metadata still falls back to the JVM projection. Nullability from @Metadata (String?, List<String?>, boxed Integer?) renders on method params/returns and properties; canonical symbol refs strip the ? marker.