# Terminal surfaces

Nothing about your habits changes. You type `elide test` the way you always have; in a Tern terminal the results
draw as a view instead of scrolling past as lines. Five commands behave this way, and none of them needs the plugin.
The plugin's part is to open the `elide://` links the views carry (see [Links](/docs/tern-workspace#elide-links)).

| Command | In a Tern terminal | Plain output kept for |
| --- | --- | --- |
| `elide test` | Results inline in the pane | `--reporter`, `--project`, a glob or missing path, redirected output |
| `elide build` | The build inline in the pane | `--inspect`, `--help`, `--progress`, `--project`, redirected output, no `elide.pkl` |
| `elide help` | The docs as a native page | `--format markdown`, redirected output |
| `elide serve` | The Server page | `--no-tui`, no terminal |
| `elide repl` | The REPL inline in the pane | Piped or redirected input or output |

Outside Tern every command prints as it does in any terminal. Scripts and other tools see the same text they always
did: a pipe or a redirect, a non-terminal stdin or `TERM=dumb` is enough to get it. `-p` counts as `--project`, and
`--` on `elide test` keeps plain output too.

## Inline and page surfaces

`elide test` and `elide build` draw inline by default: the view sits in the pane's output, and when the command ends it
stays in scrollback like printed text. A page takes the whole pane until you quit it.

| Setting | Effect |
| --- | --- |
| `--surface=inline` | Draw inline. The default. |
| `--surface=screen` | Open the full page. |
| `--surface=auto` | Same as `inline`. |
| `ELIDE_TERN_SURFACE=screen` | The default mode for every run in that environment. |

The flag wins over the variable. A flag value other than `inline`, `screen` or `auto` is an error. A variable
naming no mode makes the run use `auto`; `elide test` also prints one warning on stderr:

```text
elide: ELIDE_TERN_SURFACE='full' names no surface mode (expected inline, screen or auto); using auto
```

A Tern without inline surfaces gets the page. Outside Tern, and on any run that keeps the plain output, `--surface` is
accepted and has no effect, so scripts can always pass it. An inline view closes when its run finishes and the
command returns; the keys below act on the pages.

## `elide test` in Tern

| Level | How to get it | What it shows |
| --- | --- | --- |
| Plain text | Outside Tern, or `--reporter` | The reporter's lines. |
| Inline | `elide test` in a Tern terminal | Status, counts and the results table, with the selected test's failure beneath. |
| Tests page | `--surface=screen` | Results, Failures, Output and Coverage tabs, with rerun and cancel. |
| Project Tests page | **Run tests** in the plugin | The Tests page on a shared project session, with **Debug this test**. |

Plain text:

Inline:

Project Tests page in the workspace:

`elide test` exits nonzero when the last run failed, and `130` when a run is cancelled or interrupted before it
finishes. Test files and failure locations inside a project link to the source editor.

| Key | Action |
| --- | --- |
| `Tab`, `]` / `Shift+Tab`, `[` | Next and previous tab. |
| `j` `k`, `↑` `↓` | Select a test; on Coverage, a file. |
| `r` | Run again. |
| `c` | Run with coverage. |
| `x` | Cancel the run. |
| `d` | Debug the selected test (project Tests page). |
| `Esc` | Back out one view. |
| `q`, `Ctrl+D` | Quit from Results. |

Tests run with the same flags as a plain run: `--coverage`, `-t`, `--where` and the other
[`elide test` flags](/docs/cli-references#test) pass through. Each run saves its TAP report and runner log under
`.dev/reports/tests/tern/` in the project, or in the test file's directory outside one.

## `elide build` in Tern

| Level | How to get it | What it shows |
| --- | --- | --- |
| Plain text | Outside Tern, or a run that keeps plain output | The build's log lines. |
| Inline | `elide build` in a Tern terminal | State, error and warning counts, task progress and a card per diagnostic. |
| Build page | `--surface=screen`, or **Build project** in the workspace | The same, full pane, with **Rebuild** (`r`). |

Plain text:

Inline:

Build page from the workspace:

`x` cancels a running build; `q`, `Esc` and `Ctrl+D` close the page once the build has finished. `elide build` exits
with the build's own status, and `130` when it is cancelled or interrupted. Each run writes its diagnostics report,
which the source editor and status bar read; see [Build diagnostics](/docs/tern-build).

## `elide help` in Tern

| Level | How to get it | What it shows |
| --- | --- | --- |
| Plain text | Outside Tern | The terminal reader. |
| Help page | `elide help` in a Tern terminal | Navigation beside the page, a trail to its group and a search field. |

Plain text:

Help page:

`elide help TOPIC` opens at that topic; `elide help options` and the other command-line topics print text. Under 80 columns the page stacks the search field, the page and the navigation.
Keys and search: [`help`](/docs/cli-references#help). Links between help pages are `elide://help?topic=<slug>` URLs;
through the plugin they open in a new pane beside the one you clicked in.

## `elide serve` in Tern

| Level | How to get it | What it shows |
| --- | --- | --- |
| Plain text | `--no-tui`, or no terminal | Plain log output. |
| Terminal dashboard | `elide serve` outside Tern | Requests, logs and metrics in the terminal. |
| Server page | `elide serve` in a Tern terminal, or **Serve directory or script** | Address, state, Requests, Traces and Logs tabs, Restart and Stop. |

| Key | Action |
| --- | --- |
| `Tab`, `]` / `Shift+Tab`, `[` | Next and previous tab. |
| `j` `k`, `↑` `↓` | Select a request. |
| `r` | Restart the server. |
| `s` | Stop the server. |
| `p` | Pause or resume trace capture. |
| `e` | Show only failed traces (Traces); `Esc` shows all again. |
| `c` | Clear traces (Traces) or logs (Logs). |
| `q`, `Esc`, `Ctrl+C`, `Ctrl+D` | Quit; the server stops. |

A directory is served as static files; a script runs with its fetch handler, and `elide dev` on a script opens the
same page. The Logs tab appears with the first log line and the Traces tab once a request is captured; see
[Traces](/docs/tern-telemetry).

## `elide repl` in Tern

| Level | How to get it | What it shows |
| --- | --- | --- |
| Plain text | `elide repl` outside Tern | The terminal REPL. |
| Inline REPL | `elide repl` in a Tern terminal | A language picker, an editor, and results as they arrive. |
| Notebook | **Open REPL** in the plugin | A notebook where JavaScript and Python share live values. |

| Key | Action |
| --- | --- |
| `Enter` | Evaluate. |
| `Shift+Enter`, `Ctrl+J` | New line. |
| `Ctrl+L` | Open the language picker; `↑` `↓` choose, `Enter` switches, `Esc` closes it. |
| `↑` on the first line, then `↓` | Step through history. |
| `Tab` | Complete a `/` command. |
| `Ctrl+C` | Interrupt an evaluation. |
| `Ctrl+D` | Quit, on an empty editor. |

**Clear** sends `/clear`. The REPL's [commands](/docs/repl#commands) work inline and in the notebook. The notebook is described under
[REPL notebook](/docs/tern-workspace#repl-notebook).

## Next

The views so far live in whatever terminal you typed in. The [project workspace](/docs/tern-workspace) gives a project
its own tab, with a toolbar that opens these same pages and test runs that every view shares.

## See also

- [`elide test`](/docs/cli-references#test), [`elide build`](/docs/cli-references#build), [`elide help`](/docs/cli-references#help)