Skip to content

Improve docs #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rochala merged 2 commits into from
Mar 24, 2026
Merged

Improve docs #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c6dfa7
Improove docs
rochala Mar 24, 2026
665f659
Improve download
rochala Mar 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
210 changes: 170 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<h1 align="center">Cellar</h1>

<p align="center">
Look up the public API of any Maven-published JVM dependency from the terminal.
Look up the public API of any JVM dependency from the terminal.
</p>

---
Expand All @@ -18,72 +18,109 @@ Cellar gives agents — and humans — a single shell command that returns exact

| Format | Support |
|---|---|
| Scala 3 (TASTy) | Full — signatures, flags, companions, sealed hierarchies, givens, extensions, docstrings, source |
| Scala 3 (TASTy) | Full — signatures, flags, companions, sealed hierarchies, givens, extensions, docstrings |
| Scala 2 (pickles) | Best-effort — type information may be incomplete |
| Java (.class) | Good — signatures, members, source |
| Java (.class) | Good — signatures, members |

## Usage
## Installation

### `cellar get <coordinate> <fqn>`
Download the native binary for your platform from https://github.com/simple-scala-tooling/cellar/releases/latest, then extract and install:

Look up a single symbol — type signature, flags, members, companion, known subtypes, docstring.

```
cellar get org.typelevel:cats-core_3:2.10.0 cats.Monad
cellar get org.apache.commons:commons-lang3:3.14.0 org.apache.commons.lang3.StringUtils
```sh
tar xz -f cellar-*.tar.gz
sudo mv cellar /usr/local/bin/
```

### `cellar get-source <coordinate> <fqn>`
To verify checksums and signatures, see [RELEASING.md](RELEASING.md).

Fetch the source code from the published `-sources.jar`.
## Quick start

```
cellar get-source org.typelevel:cats-core_3:2.10.0 cats.Monad
```
```sh
# Look up a trait from cats
cellar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad

### `cellar list <coordinate> <package-or-class>`
# List top-level symbols in a package
cellar list-external org.typelevel:cats-core_3:2.10.0 cats

List all public symbols in a package or class. Supports `--limit N` (default: 50).
# Search for a method name
cellar search-external org.typelevel:cats-core_3:2.10.0 flatMap

```
cellar list org.typelevel:cats-core_3:2.10.0 cats
cellar list org.typelevel:cats-core_3:2.10.0 cats.Monad
# View source code
cellar get-source org.typelevel:cats-core_3:2.10.0 cats.Monad

# Dependency tree
cellar deps org.typelevel:cats-effect_3:3.5.4
```

### `cellar search <coordinate> <query>`
## Commands

Case-insensitive substring search across all symbol names. Supports `--limit N` (default: 50).
Cellar has two modes: **project-aware** commands that work against your current project's classpath, and **external** commands that query arbitrary Maven coordinates.

```
cellar search org.typelevel:cats-core_3:2.10.0 flatMap
cellar search io.circe:circe-core_3:0.14.6 decode
### Project-aware commands

Run from your project root. Cellar auto-detects the build tool (Mill, sbt, or scala-cli), extracts the classpath, and queries your project's code and all its dependencies.

```sh
cellar get [--module <name>] <fqn>
cellar list [--module <name>] <package>
cellar search [--module <name>] <query>
```

### `cellar deps <coordinate>`
- **Mill / sbt**: `--module` is required (e.g. `--module lib`, `--module core`)
- **scala-cli**: `--module` is not supported — omit it

Print the full transitive dependency tree.
The classpath is cached after the first run. Use `--no-cache` to force re-extraction.

### External commands

Query any published Maven artifact by explicit coordinate:

```sh
cellar get-external <coordinate> <fqn>
cellar list-external <coordinate> <package>
cellar search-external <coordinate> <query>
cellar get-source <coordinate> <fqn>
cellar deps <coordinate>
```
cellar deps org.typelevel:cats-effect_3:3.5.4
```

### Coordinates
### Command reference

| Command | Description |
|---|---|
| `get` | Symbol info from the current project (signature, flags, members, docs) |
| `get-external` | Symbol info from a Maven coordinate |
| `get-source` | Source code from a published `-sources.jar` |
| `list` | List public symbols in a package/class from the current project |
| `list-external` | List public symbols from a Maven coordinate |
| `search` | Case-insensitive substring search in the current project |
| `search-external` | Case-insensitive substring search from a Maven coordinate |
| `deps` | Print the transitive dependency tree |

### Maven coordinates

Maven coordinates must be explicit — `group:artifact:version`. The `::` shorthand is not supported.
Coordinates use the format `group:artifact:version`. The `::` shorthand is **not** supported — use the full artifact name.

```
org.typelevel:cats-core_3:2.10.0 # Scala 3
org.typelevel:cats-core_2.13:2.10.0 # Scala 2
org.apache.commons:commons-lang3:3.14.0 # Java
```

Use `latest` as the version to automatically resolve the most recent release:

```sh
cellar get-external org.typelevel:cats-core_3:latest cats.Monad
```

### Options

| Flag | Description |
|---|---|
| `--java-home <path>` | Use a specific JDK for JRE classpath |
| `-r`, `--repository <url>` | Extra Maven repository URL (repeatable) |
| `-l`, `--limit <N>` | Max results (`list` and `search` only) |
| Flag | Applies to | Description |
|---|---|---|
| `--module <name>`, `-m` | project commands | Build module name (required for Mill/sbt) |
| `--no-cache` | project commands | Skip classpath cache, re-extract from build tool |
| `--java-home <path>` | all | Use a specific JDK for JRE classpath |
| `-r`, `--repository <url>` | external commands | Extra Maven repository URL (repeatable) |
| `-l`, `--limit <N>` | `list`, `search` | Max results (default: 50) |

## Output conventions

Expand All @@ -92,20 +129,109 @@ org.apache.commons:commons-lang3:3.14.0 # Java
- **Exit 0** — success
- **Exit 1** — error

## Building
## Example output

<details>
<summary><code>cellar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad</code></summary>

## cats.Monad
```scala
trait Monad[F] extends FlatMap[F] with Applicative[F]
```
Monad.
Allows composition of dependent effectful functions.

**Flags:** abstract
**Origin:** cats.Monad
**Members:**
```scala
def flatMap[A, B](fa: F[A])(f: Function1[A, F[B]]): F[B]
def pure[A](x: A): F[A]
def flatten[A](ffa: F[F[A]]): F[A]
def iterateWhile[A](f: F[A])(p: Function1[A, Boolean]): F[A]
...
```

</details>

<details>
<summary><code>cellar list-external org.typelevel:cats-core_3:2.10.0 cats --limit 5</code></summary>

object Eval$
trait ComposedContravariantCovariant[F, G] extends Contravariant[TypeLambda]
object Later$
object Show$
trait EvalSemigroup[A] extends Semigroup[Eval[A]]
Note: results truncated at 5. Use --limit to increase.

</details>

<details>
<summary><code>cellar search-external org.typelevel:cats-core_3:2.10.0 flatMap --limit 3</code></summary>

cats.FlatMap — object FlatMap$
cats.FlatMap — trait FlatMap[F] extends Apply[F] with FlatMapArityFunctions[F]
cats.FlatMap$ — object FlatMap$
Note: results truncated at 3. Use --limit to increase.

</details>

## Using cellar with Claude Code

Add the following to your project's `CLAUDE.md` to teach Claude Code how to use cellar:

````markdown
## Cellar

When you need the API of a JVM dependency, use cellar. Always prefer cellar over hallucinating API signatures.

### Project-aware commands (run from project root)

For querying the current project's code and dependencies (auto-detects build tool):

cellar get [--module <name>] <fqn> # single symbol
cellar list [--module <name>] <package> # explore a package
cellar search [--module <name>] <query> # find by name

- Mill/sbt projects: `--module` is required (e.g. `--module lib`, `--module core`)
- scala-cli projects: `--module` is not supported (omit it)
- `--no-cache`: skip classpath cache, re-extract from build tool
- `--java-home`: override JRE classpath

### External commands (query arbitrary Maven coordinates)

For querying any published artifact by explicit coordinate:

cellar get-external <coordinate> <fqn> # single symbol
cellar list-external <coordinate> <package> # explore a package
cellar search-external <coordinate> <query> # find by name
cellar get-source <coordinate> <fqn> # source code
cellar deps <coordinate> # dependency tree

Coordinates must be explicit: `group:artifact_3:version` (use `latest` for newest version).

### Workflow

1. **Don't know the package?** → `cellar search <query>` or `cellar search-external <coordinate> <query>`
2. **Know the package, not the type?** → `cellar list <package>` or `cellar list-external <coordinate> <package>`
3. **Know the type?** → `cellar get <fqn>` or `cellar get-external <coordinate> <fqn>`
4. **Need the source?** → `cellar get-source <coordinate> <fqn>`
````

## Building from source

Requires JDK 17+ and [Mill](https://mill-build.org/).

```sh
# Fat JAR
./mill cli.assembly
java -jar out/cli/assembly.dest/out.jar get org.typelevel:cats-core_3:2.10.0 cats.Monad
java -jar out/cli/assembly.dest/out.jar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad

# Native image (GraalVM)
./mill cli.nativeImage

# Wrapper script
./scripts/cellar get org.typelevel:cats-core_3:2.10.0 cats.Monad
# Wrapper script (for development)
./scripts/cellar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad
```

### Running tests
Expand All @@ -121,3 +247,7 @@ java -jar out/cli/assembly.dest/out.jar get org.typelevel:cats-core_3:2.10.0 cat
## Tech stack

Scala 3, Cats Effect, fs2, [tasty-query](https://github.com/scalacenter/tasty-query), [Coursier](https://get-coursier.io/), [decline](https://ben.kirw.in/decline/), Mill.

## License

[MPL-2.0](LICENSE)
76 changes: 76 additions & 0 deletions SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
---
name: cellar
description: Look up the public API of any JVM dependency (Scala 3, Scala 2, Java) from the terminal. Returns type signatures, members, docstrings, and source code as Markdown.
---

# Cellar

Use cellar to look up the API of JVM dependencies instead of guessing or hallucinating signatures.

## Project-aware commands (run from project root)

Query the current project's code and all its dependencies. Cellar auto-detects the build tool (Mill, sbt, scala-cli).

cellar get [--module <name>] <fqn> # single symbol (signature, members, docs)
cellar list [--module <name>] <package> # list symbols in a package or class
cellar search [--module <name>] <query> # case-insensitive substring search

- Mill/sbt projects: `--module` is required (e.g. `--module lib`, `--module core`)
- scala-cli projects: omit `--module`
- `--no-cache`: skip classpath cache, re-extract from build tool
- `--java-home <path>`: override JRE classpath
- `-l`, `--limit <N>`: max results for `list`/`search` (default: 50)

## External commands (query arbitrary Maven coordinates)

Query any published artifact by explicit coordinate (`group:artifact:version`):

cellar get-external <coordinate> <fqn> # single symbol
cellar list-external <coordinate> <package> # list symbols
cellar search-external <coordinate> <query> # search by name
cellar get-source <coordinate> <fqn> # fetch source code
cellar deps <coordinate> # dependency tree

- Coordinates must be explicit: `group:artifact_3:version` (no `::` shorthand)
- Use `latest` as the version to resolve the most recent release
- `-r`, `--repository <url>`: extra Maven repository (repeatable)

## Workflow

1. **Don't know the package?** → `cellar search` / `cellar search-external`
2. **Know the package, not the type?** → `cellar list` / `cellar list-external`
3. **Know the type?** → `cellar get` / `cellar get-external`
4. **Need the implementation?** → `cellar get-source`

## Examples

```sh
# Look up a Scala 3 trait
cellar get-external org.typelevel:cats-core_3:2.10.0 cats.Monad

# Look up a Java class
cellar get-external org.apache.commons:commons-lang3:3.14.0 org.apache.commons.lang3.StringUtils

# List a package
cellar list-external io.circe:circe-core_3:0.14.6 io.circe

# Search for a method
cellar search-external org.typelevel:cats-core_3:2.10.0 flatMap

# Get source code
cellar get-source org.typelevel:cats-core_3:2.10.0 cats.Monad

# Dependency tree
cellar deps org.typelevel:cats-effect_3:3.5.4

# Project-aware (from a Mill project root)
cellar get --module lib cats.Monad
cellar list --module core cats
cellar search --module lib flatMap
```

## Output

- **stdout**: Markdown — ready to consume directly
- **stderr**: diagnostics (warnings, truncation notices)
- **Exit 0**: success, **Exit 1**: error
Loading