Getting Started

Install Elyra, configure a provider, and run your first session in under two minutes.

Installation

Elyra is distributed as an npm package. Install it globally:

npm install -g @elyracode/coding-agent

Then start Elyra in whatever project directory you want it to work on:

cd /path/to/project
elyra

Authentication

Elyra supports subscription-based providers via OAuth and API-key providers via environment variables or an auth file.

Option 1: Subscription Login

Start Elyra and run the /login command, then select a provider. Built-in subscription logins include:

• Claude Pro / Max
• ChatGPT Plus / Pro (Codex)
• GitHub Copilot

Option 2: API Key

Set an API key before launching Elyra:

export ANTHROPIC_API_KEY=sk-ant-...
elyra

You can also run /login and select an API-key provider to store the key in ~/.elyra/agent/auth.json.

First Session

Once Elyra starts, type a request and press Enter:

Summarize this repository and tell me how to run its checks.

By default, Elyra gives the model four tools:

Additional read-only tools (grep, find, ls) are available through tool options. Elyra runs in your current working directory and can modify files there. Use git or another checkpointing workflow for easy rollback.

CLI Flags

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

Model Options

Session Options

Mode Options

Tool Options

Resource Options

File Arguments

Prefix files with @ to include them in the message:

elyra @README.md "Summarize this"
elyra @src/app.ts @src/app.test.ts "Review these together"
elyra -p @screenshot.png "What's in this image?"

Examples

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

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

# Pipe 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"

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

Interactive Mode

The interactive 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, and errors.
• Editor — where you type. Border color indicates the current thinking level.
• Footer — working directory, session name, token/cache usage, cost, context usage, and model.

Editor Features

Message Queue

You can submit messages while the agent is still working:

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

Keybindings

All keyboard shortcuts can be customized via ~/.elyra/agent/keybindings.json. Run /reload to apply changes without restarting. Run /hotkeys to view all active bindings.

Application

Models and Thinking

Display

Editor Movement

Custom Configuration

Create ~/.elyra/agent/keybindings.json:

{
  "tui.editor.cursorUp": ["up", "ctrl+p"],
  "tui.editor.cursorDown": ["down", "ctrl+n"],
  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
}

Slash Commands

Type / in the editor to open command completion.

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

Inside Elyra, use /session, /tree, /fork, /clone, and /compact to manage sessions.

Context Files

Elyra loads context files at startup for project-specific instructions.

Add an AGENTS.md file to your project root:

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

Elyra loads:

• ~/.elyra/agent/AGENTS.md for global instructions.
• AGENTS.md or CLAUDE.md from parent directories and the current directory.

Run /reload after changing context files. 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.

Non-interactive Mode

For one-shot prompts:

elyra -p "Summarize this codebase"
cat README.md | elyra -p "Summarize this text"
elyra -p @screenshot.png "What's in this image?"

Use --mode json for JSON event output or --mode rpc for process integration.

Environment Variables