REPL

In addition to being a CLI, Coyote also has a built-in REPL (Read-Execute-Print-Loop). This enables users to quickly try out prompts, commands, configurations, and everything in between without having to modify the same command every time.

You can enter the REPL by simply typing coyote without any follow-up flags or arguments.

---

Features

The REPL has features that are intended to make your Coyote experience as easy and as enjoyable as possible! This includes things like

• Tab Autocompletion: Every command in the REPL (i.e. everything that starts with a .) has fuzzy search auto completions.
  • .<tab> to complete REPL commands
  • .model <tab> to complete chat models
  • .set <tab> to complete configuration keys
  • .set key <tab> to complete configuration values
  • .mcp auth <tab> to complete remote MCP server names
• Multi-Line Prompts: You can also type prompts that span more than one line to help organize your thoughts. This can be done in the following ways:
  • Ctrl-o to open the current input buffer in your preferred editor (either the value of editor or $EDITOR)
  • You can paste multi-line text
  • You can type ::: to start multi-line editing, and use ::: to finish it.
  • And finally, you can use hotkeys like {ctrl/shift/alt}+enter or ctrl-j to insert a new line directly in the REPL.
• History Search Press ctrl+r to search the REPL history, and navigate it with ↑↓
• Configurable Keybindings: You can switch between emacs style keybindings or vi style keybindings
• Custom REPL Prompt: You can even customize the REPL prompt to display information about the current context in the prompt
• Built-in user interaction tools: When function calling is enabled in the REPL, the user__ask, user__confirm, user__input, and user__checkbox tools are always available for interactive prompts. These are not injected in the one-shot CLI mode.

---

REPL Commands

All REPL commands begin with a . to indicate that they're not part of a prompt. The following list details the commands available in Coyote:

.model - Change the current LLM

When browsing models in the REPL, use the following legend to understand the purpose of each column in the model table:

openai:gpt-4o     128000 /     4096  |       5 /     15    👁 ⚒ 
|                 |            |             |       |     |  └─ supports function calling
|                 |            |             |       |     └─ support vision (multi-modal)
|                 |            |             |       └─ output price ($/1M)
|                 |            |             └─ input price ($/1M)
|                 |            |
|                 |            └─ max output tokens
|                 └─ max input tokens
└─ model id

For more information about how to add models to Coyote, refer to the clients documentation.

.role - Role management

Coyote offers the following commands to manage your roles:

Command	Description
.role	Create or switch to a role
.info role	Show information about the active role
.edit role	Open the active role's configuration file in your preferred text editor
.save role	Save the active role and its configurations to a configuration file
.exit role	Exit the active role

For more information about roles in Coyote and how to build them, refer to the roles documentation.

.prompt - Set a temporary role using a prompt

If you need to create a temporary role that you want to discard after use, you use .prompt. .prompt-based roles cannot be persisted to a file and saved.

.skill - Skill management

Skills are modular knowledge or capability packs the LLM can load and unload mid-conversation. Multiple skills can be loaded at once; their instructions stack and their tools/MCP servers union with the active role/agent/session.

Requires function calling. Skills depend on Coyote's function calling system. If function_calling_support: false in your global config, the .skill load and .skill unload commands refuse, and the model cannot load skills itself.

Command	Description
.skill loaded	List currently-loaded skills in this session
.skill load <name>	Load a skill into the current context (validates policy + compatibility, then refreshes scope)
.skill unload <name>	Unload a loaded skill, releasing any MCP servers it pulled in
.skill <name>	Open the skill in $EDITOR. Creates a scaffolded SKILL.md if missing

To edit an existing skill without the create-if-missing fallback, use .edit skill <name> (see the .edit section).

For more information about skills, including frontmatter fields, visibility/enforcement, auto-unload behavior, and the bundled built-in skills, see the skills documentation.

.session - Session management

Use the following commands to manage sessions in Coyote:

Command	Description
.session	Start or switch to a session
.empty session	Clear all messages for the active session
.compress session	Compress the session messages using the summarization_prompt setting in the global config
.info session	Display information about the active session
.edit session	Open the active session's configuration in your preferred text editor
.save session	Save the active session to a session configuration file
.exit session	Exit the active session

For more information on sessions and how to use them in Coyote, refer to the sessions documentation.

.agent - Chat with an AI agent

Coyote lets you build OpenAI GPT-style agents. The following commands let you interact with and manage your agents in Coyote:

Command	Description
.agent	Use an agent
.starter	Display and use conversation starters for the active agent
.clear todo	Clear the todo list and stop auto-continuation (requires auto_continue: true on the agent)
.edit agent-config	Open the agent configuration in your preferred text editor
.info agent	Display information about the active agent
.exit agent	Leave the active agent

For more information on agents in Coyote and how to create them, refer to the agents documentation.

.clear todo - Clear the todo list

Clears the todo list and stops auto-continuation. This command is available in any context (agents, sessions, roles, or bare mode) as long as auto_continue is enabled.

This is useful when:

• You gave a custom response that changes or cancels the current task
• The model is stuck in auto-continuation with stale todos
• You want to start fresh

For more information, see the Todo System documentation.

.rag - Chat with documents

RAG (Retrieval Augmented Generation) enables you to load documents into the LLM so you can ask questions about it or complete tasks using the documents as additional context.

Command	Description
.rag	Initialize or access a RAG
.edit rag-docs	Add or remove documents from the active RAG using your preferred text editor
.rebuild rag	Rebuild the active RAG to accommodate document changes
.sources rag	Show a works-cited of the sources used in the last query
.info rag	Display information about the active RAG
.exit rag	Exit the active RAG

For more information about RAG in Coyote and how to utilize it, refer to the rag documentation.

.macro - Execute a macro

Macros in Coyote are like "scripts" of commands that can be run in isolated environments; that means they do not use any active settings and use the same settings they had when written. They are created/executed using the .macro <name> command.

For more information on macros in Coyote and how to create them, refer to the macros documentation.

.file - Read files and use them as input

Coyote lets you specify any number of documents that you can load and use as ephemeral RAG to chat with the LLM. To see what files or values you can pass to it, simply run the command .file with no arguments:

openai:gpt-4o)> .file
Usage: .file <file|dir|url|%%|cmd>... [-- <text>...]

For more information about ephemeral RAG, refer to the ephemeral RAG documentation.

.vault - Manage the Coyote vault

The Coyote vault lets users store sensitive secrets and credentials securely so that there's no plaintext secrets anywhere in your configurations.

For more information about the Coyote vault, refer to the vault documentation.

.continue - Continue the previous response

When you have a response that exceeds the context length, you can use the .continue command to continue the generation of the last response.

.regenerate - Regenerate the last response

If ever your response is interrupted, or you want to try generating it again, you can use the .regenerate command to do this without having to retype your query:

.copy - Copy the last response to your clipboard

If you're trying to copy the last response (like copying some code), you can use the .copy command to copy the entire last response to your system clipboard:

.set - Adjust runtime settings

You can use .set to adjust select settings at runtime. This is useful when you're experimenting with settings and want to know how they'll affect Coyote. To persist the changes you make, be sure to update them in the global configuration file.

The following settings can be adjusted at runtime:

Setting	Type	Description
auto_continue	boolean	Enable/disable the Todo System auto-continuation
max_auto_continues	integer	Maximum number of automatic continuations
inject_todo_instructions	boolean	Inject default todo instructions into the system prompt
continuation_prompt	string	Custom continuation prompt (supports multi-word values; null to reset)
temperature	float	Model temperature parameter
top_p	float	Model top-p parameter
enabled_tools	string	Comma-separated list of enabled tools (e.g. fs_ls,fs_cat or all); the saved YAML config also accepts a list form
enabled_mcp_servers	string	Comma-separated list of enabled MCP servers (e.g. github,slack or all); the saved YAML config also accepts a list form
enabled_skills	string	Comma-separated list of enabled skills (e.g. git-master,ai-slop-remover); null clears the override
save_session	boolean	Whether to auto-save sessions
compression_threshold	integer	Token threshold for session compression
max_output_tokens	integer	Maximum output tokens for the current model
dry_run	boolean	Enable/disable dry run mode
function_calling_support	boolean	Enable/disable function calling
mcp_server_support	boolean	Enable/disable MCP server support
skills_enabled	boolean	Master switch for skills. Accepts true, false, or null (inside a session, null clears the session-level override; otherwise resets to the default true)
stream	boolean	Enable/disable streaming
save	boolean	Enable/disable saving responses
highlight	boolean	Enable/disable syntax highlighting

.edit - Modify configuration files

The .edit command lets you modify configuration files for the current mode of the REPL. It will open the selected configuration in your preferred text editor. It lets you modify the following configurations:

• .edit config - Modify the global configuration
• .edit mcp-config - Modify the MCP servers configuration file (mcp.json)
• .edit role - Modify the active role's configuration
• .edit session - Modify the active session's configuration
• .edit agent-config - Modify the active agent's configuration
• .edit rag-docs - Add or remove documents from the active RAG
• .edit skill <name> - Modify an existing skill by name

.delete - Delete configurations from Coyote

The .delete command allows you to delete entities in Coyote without having to directly run rm -rf on the configuration directory or file corresponding to the target entity. You can use it to delete the following entities:

• .delete role - Delete select roles
• .delete session - Delete select sessions
• .delete macro - Delete select macros
• .delete skill - Delete select skills
• .delete rag - Delete select RAGs
• .delete agent-data - Delete select agent's configurations and all tools

.install - Reinstall bundled assets

Coyote's built-in agents, macros, and tool functions (and an MCP config template) are written to your configuration directory on first run and are not overwritten afterward, so your local edits survive Coyote updates. The .install command force-overwrites a category of bundled assets with the versions packaged in the current Coyote build. This is useful when an update ships improved built-ins you want to adopt.

Command	Description
.install agents	Reinstall the built-in agents
.install macros	Reinstall the built-in macros
.install skills	Reinstall the built-in skills
.install functions	Reinstall the built-in tool functions (leaves your mcp.json alone)
.install mcp_config	Replace mcp.json with the bundled template (see warning below)

The same operation is available from the command line: coyote --install <category> (e.g. coyote --install agents).

.install prompts for confirmation before overwriting anything. Assets you created yourself are never touched. Only Coyote's own bundled assets are replaced.

Warning: .install mcp_config is destructive in a way the others are not. It replaces your entire mcp.json (your configured MCP servers and any secret references in them) with Coyote's bundled template. The other categories only overwrite Coyote's built-in assets and leave your custom ones alone.

.install remote - Install assets from a git repository

The .install remote command installs agents, roles, macros, tools, and MCP servers from any git repository whose layout mirrors Coyote's user config directory. This is the primary mechanism for sharing and reusing Coyote configurations.

Command	Description
.install remote <git-url>	Install everything the repo provides
.install remote <git-url>#<ref>	Pin to a tag, branch, or commit (e.g. #v1.0.0, #main)
.install remote <git-url> --filter <category>	Restrict to one of agents, roles, skills, macros, functions, mcp_config
.install remote <git-url> --force	Skip all conflict prompts; overwrite local files unconditionally

The CLI equivalent is coyote --install-from <git-url> (with --filter and --install-force accepting the same values).

See Sharing Configurations for the expected repo layout, conflict resolution, secret handling, and the coyote-config-template starter you can fork.

.update - Update Coyote

The .update command updates the Coyote binary itself to the latest release, without leaving the REPL to run a separate installer.

Command	Description
.update	Update to the latest release
.update latest	Update to the latest release
.update <version>	Update to a specific release (e.g. .update v0.4.0)

A version may be given either bare (0.4.0) or v-prefixed (v0.4.0). If Coyote is already on the requested version, it says so and makes no changes; otherwise it downloads the matching build, replaces the binary, and reports the new version. Restart Coyote for the update to take effect.

If Coyote was installed via Homebrew or cargo install, .update prints a warning (updating in place desyncs your package manager) and asks for confirmation before continuing; for those installs, prefer brew upgrade coyote or cargo install --locked coyote-ai.

.update cannot be run from inside a macro. The same operation is available on the command line as coyote --update. For full CLI details, including the --force flag for non-interactive updates, see the Installation documentation.

.info - Display information about the current mode

The .info command provides useful information about different modes that Coyote may be operating in. It's helpful if you want a quick understanding of the system info, a role's configuration, an agent's configuration, etc.

The following entities are supported:

Command	Description
.info	Display system information (identical to the --info flag)
.info role	Display information about the active role
.info session	Display information about the active session
.info agent	Display information about the active agent
.info rag	Display information about the active RAG
.info tools	List every tool that would be sent in the next chat completion request (composed across role, agent, skills, and MCP filters). Errors when function_calling_support is disabled.
.info todo	Show the current todo list driving auto-continuation (goal, progress count, and per-task status). Only available when auto_continue is enabled.

.mcp auth - Authenticate with an OAuth-protected MCP server

Some remote MCP servers (such as Notion, Jira, etc.) require OAuth authentication before they can be used. Run this command once per server to complete the authorization flow:

.mcp auth <server-name>

where <server-name> matches the key in your mcp.json file. Tab completion is available.

What happens:

1. Coyote discovers the server's OAuth endpoints automatically via RFC 9728 metadata discovery.
2. If the server supports Dynamic Client Registration (RFC 7591), Coyote registers itself automatically, meaning no oauth_client_id configuration is required.
3. Your browser opens to the server's authorization page. Log in and approve access.
4. The token is saved to <cache_dir>/coyote/oauth/ and loaded automatically on subsequent startups.
5. Tokens are refreshed automatically when they expire.

If a server requires authentication but you haven't run .mcp auth yet, Coyote will skip that server at startup with a warning rather than failing outright. The warning tells you exactly which command to run.

The same flow is available outside the REPL via coyote --auth-mcp <server-name>.

For full configuration options and an example for Notion, see the MCP Servers documentation.

.authenticate - Authenticate the current model client via OAuth

The .authenticate command will start the OAuth flow for the current model client if

• The client supports OAuth (See the clients documentation for supported clients)
• The client is configured in your Coyote configuration to use OAuth via the auth: oauth property

.exit - Exit an agent/role/session/rag or the Coyote REPL itself

The .exit command is used to move between modes in the Coyote REPL.

Command	Description
.exit role	Exit the active role
.exit session	Exit the active session
.exit agent	Exit the active agent
.exit rag	Exit the active RAG
.exit	Exit the Coyote REPL

.help - Show the help guide

Just like with any shell or REPL, you sometimes need a little help and want to know what commands are available to you. That's when you use the .help command.

!<command> - Run an arbitrary shell command

Prefix any line with ! to run the rest of the line as a shell command instead of sending it to the LLM. Output streams straight to your terminal in real time, and you don't spend any tokens and no output is sent to the LLM.

Particularly useful inside coyote --sandbox where you need to modify the sandbox itself without running sbx exec <name> -- <command>; e.g., !apt-get install httpie, !git pull, !cargo build, or anything else you'd normally run in a terminal, without leaving the REPL.

How it works

• The line is passed to your shell as <SHELL> -c "<your command>". Note that Coyote does not inspect or sanitize the command, but rather the shell parses it. So pipes (!ls | grep yaml), redirects (!cat > /tmp/out), env-var expansion (!echo "$HOME"), globbing (!ls *.toml), command substitution (!grep ERROR $(ls *.log)), and inline env vars (!FOO=bar cmd) all work exactly like they do in a normal terminal.
• The ! must be the first character of the line. Lines like !ls (leading whitespace), echo !foo (inline !), or ! (just whitespace after) are not recognized as shell pass-through; The first two go to the LLM, the last prints a usage hint.
• Press Ctrl-C at any time to interrupt a long-running command. SIGINT propagates to the child shell; the command stops, [exit 130] prints, and you return to the prompt.
• If the command exits non-zero, [exit N] is printed. Successful commands return to the prompt silently.

Limitations

• !cd /tmp does not persist. Each !cmd runs in a fresh child shell, so subsequent !pwd will show the REPL's original working directory, not /tmp.
• The command is not written to your shell's history file (~/.bash_history, ~/.zsh_history). It is, however, saved in the REPL's reedline history (use up-arrow to recall).