ja git:20261104.4e557e3A

Immutable. This exact content never changes and is served at /api/v1/blob/b50cf9aee65bfbc7.

---
name: ja
description: Develop and understand Java projects with the `ja` command-line environment. Use for build-aware Java code navigation, source and API lookup, Gradle or Maven project contexts, module dependencies, formatting, compilation, tests, benchmarks, packaging, and direct use of JDK tools.
---

# ja

`ja` is a terminal development environment for Java. It discovers Java module, Gradle, and Maven projects and supplies commands and tools with the sources, dependencies, class paths, module paths, and Java options for the selected project context.

The working directory selects the build and provides a useful focus. Java insight commands search every discovered Java context when run at the build root, narrow to an enclosing project or source file when possible, and merge duplicate results. Use `-C <directory>` to change the working directory before project discovery, or `-p <selector>` to focus a command on an explicit project context. Run `ja <command> --help` for complete command syntax.

## Select the project context

When the automatic selection is not obvious, start with:

```bash
ja projects
```

The output lists every discovered project context and marks the current working-directory or requested selection. Use the selector from the first column with `-p` when a question should be restricted to one context.

Gradle selectors can identify a project, source set, and class path:

```bash
ja -p :app/main/compile describe file src/main/java/example/App.java
ja -p :app/test/runtime find callers example.App.start
```

Maven selectors can identify a reactor project and scope:

```bash
ja -p example:app/compile describe type example.App
ja -p example:app/test find usages example.App
```

Use a compile context for questions about compile-time visibility. Use a runtime context for whole-program relationships when runtime-only dependencies may contribute callers, implementations, or types. Select the source set containing the source under investigation.

Do not construct class paths or module paths by hand when `ja` has discovered the project. The selected context is applied to `ja` commands and compatible tools automatically.

## Understand Java code

Use `ja` semantic commands for questions about Java declarations, resolved types, origins, and relationships:

```bash
ja describe module <module>
ja describe file <source-file>
ja describe type <type>
ja describe member <member>
ja describe types <type-or-source-file>
ja describe origin <symbol>
ja source <symbol>
ja doc <symbol>
ja find declarations <name-query>
ja find usages <type-or-member>
ja find callers <type-or-method>
ja find callees <type-or-method>
ja find impl <type-or-method>
ja find supertypes <type>
```

Choose the command according to the question:

- `describe module` shows a module declaration.
- `describe file` lists declarations in one source or class file.
- `describe type` shows a type and its API.
- `describe member` shows a method or field.
- `describe types` lists compiler-resolved type identities referenced by a type or source file.
- `describe origin` shows the source, module, or dependency artifact from which a symbol resolves.
- `source` prints the implementation source for a package, type, or member.
- `doc` finds local API documentation; `doc --browse` opens the documentation browser.
- `find declarations` searches named type and member declarations. Use repeatable `--kind` options to restrict results to `module`, `package`, `type`, `class`, `interface`, `enum`, `record`, `annotation`, `method`, or `field`; `type` includes all type declarations.
- `find usages` finds semantic references to a type or member.
- `find callers` finds calls to a method, or calls to executables declared by a type.
- `find callees` finds calls made by a method, or by executables declared by a type.
- `find impl` finds subtypes of a type or overriding methods.
- `find supertypes` finds parent types.

Use a fully qualified type or member when a simple name is ambiguous. Command completion can supply symbols and project selectors when shell completions are installed.

`find` searches every discovered project-source context by default. This is the complete project-source search, not a single source set. Do not add a wider option merely to confirm its results. Add `--external` only when dependency or other external application declarations are part of the question, or `--all` when JDK system-module declarations are also required:

```bash
ja find declarations --kind type Queue
ja find callers --external example.Library.run
ja find callers --all java.lang.String.repeat
```

These queries use the resolved Java inputs for the applicable discovered contexts and are global at the build root. Add `-p <context>` when compile-time or runtime visibility in one context is the question. A successful semantic query is sufficient evidence for the declarations or relationships it reports. Use ordinary text search for lexical questions, arbitrary line ranges, comments, strings, non-Java files, and languages other than Java; do not repeat semantic queries with text search merely to reconstruct the same result.

## Use packaged Java tools

List and run packaged Java tools:

```bash
ja tool
ja tool javac --version
ja tool jdeps
```

`ja tool <name>` runs the selected Java tool with compatible project options supplied automatically. Pass tool-specific arguments after the name. Use `ja skill` to list tools that publish Agent Skills and `ja skill <tool>` to print one.

## Work with module projects

`ja` can directly manage projects defined by `module-info.java` without a separate build configuration:

```bash
ja init --main-class example.Main com.example.app
ja require org.apache.commons.text@1.13.1
ja fmt
ja compile
ja run
ja test
ja bench
```

Other module workflows include:

- `ja generate` updates generated source.
- `ja list` lists observable modules.
- `ja assemble <directory>` creates module and application artifacts.
- `ja install` installs a module as a command.
- `ja maven export` generates Maven build POMs.
- `ja maven install` installs modules into the local Maven repository.
- `ja maven deploy` and `ja maven deploy-central` publish module artifacts.

Use these module commands for `ja` module projects. In Gradle and Maven projects, do not choose or replace the project's formatting and build workflow merely because `ja` provides a command. Follow the project's conventions and the user's intent, using `ja` for project-aware insight and compatible tools.