# Elide for AI Agents

> Run Elide non-interactively from an AI agent or CI: environment variables, timeouts, exit codes, commands that need a terminal, and collecting diagnostics.

Elide runs, builds, tests and formats JavaScript, TypeScript, Python, Java and Kotlin projects. When Elide detects an
agent harness, its output is plain and non-interactive; `ELIDE_AGENT=1` forces this.

## Invocation

```bash
NO_COLOR=1 ELIDE_LOG=warn ELIDE_ERROR_FORMAT=plain CI=1 \
  elide --ignore-version --timeout=120s <command>
```

`--ignore-version` ignores a project `.elideversion` pin. `ELIDE_ERROR_FORMAT=plain` sends program output to stdout
and uncaught errors to stderr. `--quiet` silences progress only.

## Commands that need a terminal

| Interactive | Use instead |
| --- | --- |
| `elide repl`, bare `elide python` | `elide run <file>`, `elide python <file>`, or an inline `-s` snippet |
| `elide init` | `elide init --plain --skip-defaults --template <id>`; ids from `elide init --templates --json` |
| `elide adopt` | `elide adopt --non-interactive --build <strategy> --harness <harness> --approval <mode>` |
| `elide serve`, `elide dev` | Add `--no-tui`. |
| `elide help` | `elide help <topic> --format=markdown` |

`elide adopt` launches `codex`, `claude` or `omp`, and `upgrade`, `setup` and `use` change the installation; run them
only when asked. `--approval` must be `auto-approve` or `yolo`.

## Exit 0 with no work done

- `elide test` with no tests prints `No tests found.`
- Plain `elide install` installs Maven only; use `--workspace` or `--ecosystems=npm` for `package.json`.
- `--workspace` skips `dependencies.pypi`; `--verbose` reports the skip on stderr.
- Without a terminal, `elide repl` and bare `elide python` read stdin; empty stdin runs nothing.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success, help, or version output. |
| `1` | The command or guest program ran and failed. |
| `2` | Invalid CLI usage or an unresolved run target. |
| `3` | `--heap-dump-on-oom` wrote a heap dump after an out-of-memory error. |
| `124` | `--timeout` expired. |
| other | The guest program or tool chose its own code. |

## Commands

| Command | Use |
| --- | --- |
| `elide run <file>` | Run a program; script arguments follow `--`. |
| `elide python <file>` | Run with Python-style arguments. |
| `elide build --inspect` | List project task names. |
| `elide test <path>` | Run tests; raise `--concurrency` to parallelize. |
| `elide project export` | Print the manifest as JSON; `--format=pom` or `--format=intellij` for other tools. |
| `elide classpath <sourceSet>:<usage>` | Print a resolved classpath, e.g. `test:runtime`. |
| `elide install` | Install Maven dependencies; `--ecosystems=npm` for npm, `--workspace` for all. |
| `elide format --list-files -- --dry-run <path>` | Name files that need formatting; exit `1` if any. |

`elide install` accepts `--with=sources` and `--with sources`; `--with:sources` is not accepted. `elide format` has
no `--check`; `--set-exit-if-changed` is accepted but not required. In a project, prefer `elide run` and
`elide build` to `java`, `javac`, `kotlinc` and `jar`.

## Running a script

`elide run <script>` resolves `<script>` in this order:

1. An inline snippet, when `-s`, `--snippet` or `--code` is present.
2. A **file** that exists. `.java` and `.kt` compile first.
3. A **named script**: `scripts` in `elide.pkl`, a `package.json` script, a `pyproject.toml` entry point, then a
   `node_modules/.bin` binary.
4. For a bare `elide run`: `entrypoint` from `elide.pkl`, then `jvm.main`.

Anything else exits `2` and lists every location searched.

## More documentation

`elide agent help <topic>` prints a page by slug, title, or command name; an approximate match prints the closest
page and exits `1`. `elide help --format=markdown` lists every page. The same pages are at https://elide.help.
Agentic engineering (https://elide.help/docs/agentic-engineering) covers both MCP servers and reporting.

## Diagnostics and bug reports

`elide agent diagnostics --json` reports the version, platform, and crash-report directory (`crash_root`).
`elide agent bug` prints a report body and issue URL; it submits nothing. `--kind bug|perf|expectation|feature --json`
prints an `elide.report/1` skeleton instead.
`elide agent perf [--runs 10] [--warmup 3] [--baseline "<command>"] [--against <version>] [--json] -- <command>` times a
command locally; `--baseline` measures another command the same way and `--against` an installed Elide version. It
never downloads. For servers, measure with `wrk` or `oha`.

The docs MCP server at https://elide.help/mcp searches the documentation and samples, and accepts these reports: bugs,
slow runs, missed expectations, and missing features. For immediate help, ask on Discord at https://elide.dev/discord.