# Using Elyra

This page collects day-to-day usage details that do not fit on the quickstart page.

## Interactive Mode

<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>

The interface has four main areas:

- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
- **Editor** - where you type; border color indicates the current thinking level
- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model

The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.

### Editor Features

| Feature | How |
|---------|-----|
| File reference | Type `@` to fuzzy-search project files |
| Path completion | Press Tab to complete paths |
| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
| Shell command | `!command` runs and sends output to the model |
| Hidden shell command | `!!command` runs without sending output to the model |
| External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` |

See [Keybindings](keybindings.md) for all shortcuts and customization.

## Slash Commands

Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.

| Command | Description |
|---------|-------------|
| `/login`, `/logout` | Manage OAuth or API-key credentials |
| `/model` | Switch models |
| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
| `/settings` | Thinking level, theme, message delivery, transport |
| `/theme [name]` | Open theme selector with live preview, or switch directly (autocomplete enabled) |
| `/resume` | Pick from previous sessions |
| `/new` | Start a new session |
| `/name <name>` | Set session display name |
| `/session` | Show session file, ID, messages, tokens, and cost |
| `/tree` | Jump to any point in the session and continue from there |
| `/rewind` | Rewind session and file state to a previous checkpoint |
| `/fork` | Create a new session from a previous user message |
| `/clone` | Duplicate the current active branch into a new session |
| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
| `/cost` | Show session token usage, estimated cost, and context window utilization |
| `/diff` | Show uncommitted git changes with syntax-highlighted diff output |
| `/pin <path>` | Pin a file to context so its contents survive compaction and are injected on every call |
| `/unpin <path>` | Remove a pinned file |
| `/pins` | List currently pinned files |
| `/blueprint [name]` | Apply a session blueprint from `.elyra/blueprints/` or `~/.elyra/agent/blueprints/` (supports YAML frontmatter with `pin` directives) |
| `/copy` | Copy last assistant message to clipboard |
| `/export [file]` | Export session to HTML |
| `/share` | Upload as private GitHub gist with shareable HTML link |
| `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
| `/goal <command>` | Set a goal: agent keeps working until the command exits with code 0 |
| `/update` | Update Elyra to the latest version and restart |
| `/hotkeys` | Show all keyboard shortcuts |
| `/changelog` | Display version history |
| `/quit` | Quit elyra |

## Message Queue

You can submit messages while the agent is still working:

- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
- **Escape** aborts and restores queued messages to the editor.
- **Alt+Up** retrieves queued messages back to the editor.

On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want elyra to receive the shortcut.

Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.

## Sessions

Sessions are saved automatically to `~/.elyra/agent/sessions/`, organized by working directory.

```bash
elyra -c                  # Continue most recent session
elyra -r                  # Browse and select a session
elyra --no-session        # Ephemeral mode; do not save
elyra --session <path|id> # Use a specific session file or session ID
elyra --fork <path|id>    # Fork a session into a new session file
```

Useful session commands:

- `/session` shows the current session file and ID.
- `/tree` navigates the in-file session tree and can summarize abandoned branches.
- `/rewind` rolls back both conversation and file state to a previous checkpoint.
- `/fork` creates a new session from an earlier user message.
- `/clone` duplicates the current active branch into a new session file.
- `/compact` summarizes older messages to free context.

See [Sessions](sessions.md) and [Compaction](compaction.md) for details.

## Context Files

Elyra loads `AGENTS.md` or `CLAUDE.md` at startup from:

- `~/.elyra/agent/AGENTS.md` for global instructions
- parent directories, walking up from the current working directory
- the current directory

Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.

### System Prompt Files

Replace the default system prompt with:

- `.elyra/SYSTEM.md` for a project
- `~/.elyra/agent/SYSTEM.md` globally

Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.

## Exporting and Sharing Sessions

Use `/export [file]` to write a session to HTML.

Use `/share` to upload a private GitHub gist with a shareable HTML link.

## CLI Reference

```bash
elyra [options] [@files...] [messages...]
```

### Package Commands

```bash
elyra install <source> [-l]     # Install package, -l for project-local
elyra remove <source> [-l]      # Remove package
elyra uninstall <source> [-l]   # Alias for remove
elyra update [source|self|elyra]   # Update elyra and packages; skips pinned packages
elyra update --extensions       # Update packages only
elyra update --self             # Update elyra only
elyra update --extension <src>  # Update one package
elyra list                      # List installed packages
elyra config                    # Enable/disable package resources
```

See [Elyra Packages](packages.md) for package sources and security notes.

### Diagnostics

```bash
elyra doctor                    # list the subcommands
elyra doctor preflight          # validate configured defaults, offline
elyra doctor models             # live-verify providers behave as the registry claims
elyra doctor routing            # per-model outcome measurements from the local ledger
elyra doctor resources          # running Elyra instances, their memory and CPU time
```

| Command | What it answers |
|---------|-----------------|
| `preflight` | Are my configured defaults still real models, and is there a newer one? Offline — it reads the registry rather than the network |
| `models` | Does this provider actually behave the way the registry says, including thinking mode? **Makes real API calls**, so it costs a little. `--provider`, `--model` and `--max <n>` narrow it |
| `routing` | Which models are failing me? Turn success, edit failures, retries and failovers, measured locally and never sent anywhere |
| `resources` | What is Elyra costing this machine right now? |

`elyra doctor resources` lists every running instance with its age, accumulated CPU
time and memory — including the language servers and headless browsers it started,
which are the part people do not think to look for. Idle Elyra uses no CPU, but a
forgotten instance holds its memory, so an instance that is both large and more than
a day old is flagged with a kill hint you can paste. Not available on Windows yet.

`preflight` exits non-zero when it finds a problem, so it can gate a script.

### Modes

| Flag | Description |
|------|-------------|
| default | Interactive mode |
| `-p`, `--print` | Print response and exit |
| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
| `--export <in> [out]` | Export a session to HTML |

In print mode, elyra also reads piped stdin and merges it into the initial prompt:

```bash
cat README.md | elyra -p "Summarize this text"
```

### Model Options

| Option | Description |
|--------|-------------|
| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
| `--api-key <key>` | API key, overriding environment variables |
| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
| `--list-models [search]` | List available models |

### Session Options

| Option | Description |
|--------|-------------|
| `-c`, `--continue` | Continue the most recent session |
| `-r`, `--resume` | Browse and select a session |
| `--session <path\|id>` | Use a specific session file or partial UUID |
| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
| `--session-dir <dir>` | Custom session storage directory |
| `--no-session` | Ephemeral mode; do not save |

### Tool Options

| Option | Description |
|--------|-------------|
| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
| `--no-tools`, `-nt` | Disable all tools |

Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.

Key tool behaviors:

- **`read`** returns a structural outline (function/class signatures with line numbers) for files over 150 lines. Use `offset` and `limit` to read specific sections. Each line is annotated with a content hash for precise edit targeting.
- **`edit`** runs TypeScript diagnostics after each successful edit and reports new errors to the agent immediately. Hash annotations from `read` output are stripped transparently.

### Resource Options

| Option | Description |
|--------|-------------|
| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
| `--no-extensions` | Disable extension discovery |
| `--skill <path>` | Load a skill; repeatable |
| `--no-skills` | Disable skill discovery |
| `--prompt-template <path>` | Load a prompt template; repeatable |
| `--no-prompt-templates` | Disable prompt template discovery |
| `--theme <path>` | Load a theme; repeatable |
| `--no-themes` | Disable theme discovery |
| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |

Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:

```bash
elyra --no-extensions -e ./my-extension.ts
```

### Other Options

| Option | Description |
|--------|-------------|
| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
| `--append-system-prompt <text>` | Append to system prompt |
| `--verbose` | Force verbose startup |
| `-h`, `--help` | Show help |
| `-v`, `--version` | Show version |

### File Arguments

Prefix files with `@` to include them in the message:

```bash
elyra @prompt.md "Answer this"
elyra -p @screenshot.png "What's in this image?"
elyra @code.ts @test.ts "Review these files"
```

### Examples

```bash
# Interactive with initial prompt
elyra "List all .ts files in src/"

# Non-interactive
elyra -p "Summarize this codebase"

# Non-interactive with piped stdin
cat README.md | elyra -p "Summarize this text"

# Different model
elyra --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix
elyra --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
elyra --model sonnet:high "Solve this complex problem"

# Limit model cycling
elyra --models "claude-*,gpt-4o"

# Read-only mode
elyra --tools read,grep,find,ls -p "Review the code"
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `ELYRA_CODING_AGENT_DIR` | Override config directory; default is `~/.elyra/agent` |
| `ELYRA_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
| `ELYRA_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
| `ELYRA_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
| `ELYRA_SKIP_VERSION_CHECK` | Skip the Elyra version update check at startup. This prevents the `elyracode.app` latest-version request |
| `ELYRA_TELEMETRY` | Override install/update telemetry: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
| `ELYRA_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
| `VISUAL`, `EDITOR` | External editor for Ctrl+G |

## Design Principles

Elyra keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.

It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.

For the full rationale, see the design discussion in the project documentation.