Modes

The epi CLI supports two primary modes of operation: interactive mode for ongoing conversations and print mode for one-shot tasks.

Interactive Mode

The default mode. Launches a streaming REPL where you can have a back-and-forth conversation with the agent.

# Start interactive mode
epi

# Start with an initial prompt
epi "Help me refactor the auth module"

Features

Streaming responses — Text is displayed as it's generated
Tool execution display — Tool calls are shown with their arguments and results
Session persistence — Conversation is automatically saved
Readline input — Standard terminal input with history

Commands

In interactive mode, the following commands are available:

Command	Description
`/help`	Show available commands.
`/skills`	List loaded skills.
`/skill:<name>`	Invoke a skill by name.
`/login`	Login to the OAuth provider (Anthropic).
`/logout`	Logout from the OAuth provider.
`/quit`, `/exit`	Exit the CLI.
`Ctrl+C`	Exit the CLI.

Display Format

On startup, interactive mode displays:

Provider and model information
Loaded skills (when --verbose is enabled)
Session file location

During execution, tool calls are shown as [tool_name] with a preview of their arguments, followed by the result.

Print Mode

Non-interactive mode for scripting and automation. Processes the prompt and exits.

# Basic usage
epi -p "List all TypeScript files in src/"

# With file input
epi -p @src/index.ts "Explain this file"

# Piped input
git diff | epi -p "Summarize these changes"

Text Output (default)

By default, print mode outputs only the final text response:

$ epi -p "What is 2 + 2?"
2 + 2 = 4

JSON Output

Use --mode json to get structured output:

$ epi -p --mode json "What is 2 + 2?"
{
  "type": "result",
  "text": "2 + 2 = 4",
  "stepCount": 0,
  "usage": {
    "input": 42,
    "output": 12
  }
}

The JSON output includes:

Field	Type	Description
`type`	string	Always `"result"`.
`text`	string	The agent's text response.
`stepCount`	number	Number of tool steps executed.
`usage`	object	Token usage (input and output counts).

Combining Modes with Options

# Read-only analysis in print mode
epi -p --tools readonly "Review the code in src/"

# Use a specific model in interactive mode
epi --provider openai --model gpt-4o

# Ephemeral session with higher thinking
epi --no-session --thinking high "Design a caching system"

# Custom max steps for complex tasks
epi --max-steps 100 "Refactor the entire auth module"