Using Elyra

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

Interactive Mode

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

See Keybindings 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.

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 if you want elyra to receive the shortcut.

Configure delivery in Settings with steeringMode and followUpMode.

Sessions

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

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.
• /handoff <goal> starts a fresh session for the next task, carrying over only the context that goal needs. Unlike /compact, the old session stays as it was.

Commits the agent makes carry an Elyra-Session: trailer, so elyra --session <id> opens the conversation behind a commit (see gitSessionTrailer in Settings).

See Sessions and Compaction 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

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

Package Commands

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 for package sources and security notes.

Diagnostics

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

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.

Shell Completions

elyra completions <bash|zsh|fish> prints a Tab completion script for subcommands, flags, and flag values (--provider, --thinking, --mode, paths). The script is generated from the installed version; completing never starts Elyra.

source <(elyra completions bash)     # ~/.bashrc
source <(elyra completions zsh)      # ~/.zshrc, after compinit
elyra completions fish | source      # ~/.config/fish/config.fish

Open a new shell after updating Elyra to pick up new flags.

Modes

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

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

Model Options

Session Options

Tool Options

Built-in tools: read, bash, edit, write, grep, find, ls, skill_write, extension_write, decision_record, oracle, find_sessions, read_session. Active by default: all except grep, find, and ls (decision_record only when decisionLog is not off). skill_write, extension_write, and decision_record ask for approval before saving; see Settings.

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.
• oracle asks a second model for a second opinion: one call with high reasoning, no tools, and no view of the conversation, only the question, context, and files the agent passes. The agent uses it when stuck, before risky changes, or when you ask ("ask the oracle whether..."). The model is oracle.model if set, else the smart routing powerful tier, else the closest model from another provider, else the current model. Its cost counts toward /cost, budgets, and the Elyra-Cost trailer. Disable with oracle.enabled: false (see Settings).
• find_sessions searches earlier sessions of this project (or all projects) with the same query syntax as /resume.
• read_session reads an earlier session by id prefix or path and has a model extract what the current task needs (the fast smart routing tier when configured, else the current model). Type @@ in the editor to search sessions and insert a @session:<id> mention; ids in Elyra-Session commit trailers work too.

Resource Options

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

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

Other Options

File Arguments

Prefix files with @ to include them in the message:

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

Examples

# 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

Design Principles

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

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

MCP follows the same rule: the client is the @elyracode/mcp package, bundled with Elyra so it works out of the box, built on core primitives (project trust, extension credentials, deferred tools, child-agent context) that any extension can use. See MCP and Project Trust.

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