REPL Commands¶

Complete reference for all REPL meta-commands. These commands start with : and work the same in every language (run, run python, run go, etc.).

Shell escape¶

:! CMD¶

Run a shell command with inherited stdin, stdout, and stderr. Output goes directly to your terminal.

python>>> :! echo hello
hello
python>>> :! ls -la

:!! CMD¶

Run a shell command and capture stdout and stderr, then print them.

python>>> :!! echo captured
captured
python>>> :!! pwd
/Users/you/project

Command Overview¶

:help¶

Display available commands and language shortcuts.

• :help — Show full help.
• :help :cmd — Show help for one command (e.g. :help load, :help :edit).
• :commands — List each :cmd with a one-line description (no formatting; for scripts).
• :quickref — One-screen cheat sheet (all commands + language shortcuts).

Usage¶

>>> :help
>>> :help load
>>> :commands
>>> :quickref

Example¶

>>> :help
Commands:
  :help                 Show this help message
  :languages            List available languages
  :versions [id]        Show toolchain versions
  :lang <id>            Switch to language <id>
  :detect on|off        Enable or disable auto language detection
  :reset                Reset the current language session
  :load <path>          Execute a file in the current language
  :save <path>          Save session history to a file
  :history [n]          Show last n entries (default: 25)
  :install <pkg>        Install a package for the current language
  :bench [N] <code>     Benchmark code N times (default: 10)
  :type                 Show current language and session status
  :exit, :quit          Leave the REPL
Any language id or alias works as a shortcut, e.g. :py, :cpp, :csharp, :php.

:languages¶

List all languages supported by the run tool.

Usage¶

>>> :languages

:versions [id]¶

Show toolchain versions for all languages, or a single language.

Usage¶

>>> :versions
>>> :versions python

Example¶

>>> :languages
available languages: bash, c, cpp, crystal, csharp, dart, elixir, go, groovy, haskell, java, javascript, julia, kotlin, lua, nim, perl, php, python, r, ruby, rust, swift, typescript, zig

Description¶

This command displays a comma-separated list of all programming languages that the run tool supports. Note that this shows the languages built into run, not which language runtimes or compilers are actually installed on your system. To execute code in a specific language, you still need to have that language's runtime or compiler installed

:lang <id>¶

Switch to a specific programming language.

Usage¶

>>> :lang <language_name>

Parameters¶

• <language_name> - Language name or alias (e.g., python, py, js, rust)

Examples¶

# Switch to Python
>>> :lang python
switched to python

# Use an alias
>>> :lang py
switched to python

# Switch to JavaScript
>>> :lang javascript
switched to javascript

# Use short alias
>>> :lang js
switched to javascript

Language Shortcuts¶

Instead of :lang <name>, use shortcuts:

>>> :py        # Switch to Python
>>> :js        # Switch to JavaScript
>>> :rust      # Switch to Rust
>>> :go        # Switch to Go
>>> :c         # Switch to C
>>> :cpp       # Switch to C++
>>> :java      # Switch to Java
>>> :rb        # Switch to Ruby
>>> :bash      # Switch to Bash

State Behavior¶

When switching languages:

1. Current language state is preserved
2. New language starts fresh (or resumes previous session)
3. Switching back restores the previous state

>>> :py
python>>> x = 10

>>> :js
javascript>>> let y = 20

>>> :py
# Back to Python, x still exists
python>>> x
10

:detect on|off¶

Control automatic language detection.

Usage¶

>>> :detect <on|off>

Parameters¶

• on - Enable auto-detection
• off - Disable auto-detection

Examples¶

# Enable auto-detection
>>> :detect on
auto-detect enabled

>>> print('hello')  # Auto-detects as Python
hello

# Disable auto-detection
>>> :detect off
auto-detect disabled

>>> console.log('hello')  # Stays in current language
# Error: current language doesn't recognize this syntax

When to Use¶

Enable auto-detection when: - Experimenting with different languages - Writing snippets with distinctive syntax - Quick testing

Disable auto-detection when: - Working in a single language - Code has ambiguous syntax - Need predictable behavior

Directory and bookmarks¶

:cd [path]¶

Change the current working directory. Without arguments, print the current directory.

• :cd - — Go back to the previous directory (from the directory stack).
• :cd -b <name> — Go to the directory saved as bookmark name (see :bookmark).

python>>> :cd /tmp
/tmp
python>>> :cd -
/home/you/project

:dhist [n]¶

Print the last n directories in the directory history (default 10). The stack is updated when you use :cd <path> or :cd -b <name>.

:bookmark <name> [path]¶

Save a bookmark. With only name, use the current directory. With path, use that absolute path. Bookmarks are stored in ~/.run_bookmarks and persist across sessions.

• :bookmark -l — List all bookmarks.
• :bookmark -d <name> — Delete the bookmark name.

python>>> :bookmark proj /home/you/project
[bookmark 'proj' -> /home/you/project]
python>>> :cd -b proj
/home/you/project

:env [VAR[=val]]¶

List, get, or set environment variables. No arguments: list all. One argument VAR: print value. One argument VAR=val or two arguments VAR val: set.

python>>> :env
HOME=/home/you
PATH=/usr/bin:...
python>>> :env RUN_TEST 1
python>>> :env RUN_TEST
1

:edit [path]¶

Open $EDITOR (or vi/notepad); on save and exit, execute the file in the current session. No path = create and edit a temp file, then execute it.

Logging¶

:xmode plain | context | verbose¶

Control how much stderr (e.g. exception tracebacks) is shown after a failed run.

With no argument, :xmode prints the current mode.

Usage¶

>>> :xmode
exception display: verbose (plain | context | verbose)

>>> :xmode plain
>>> :xmode context
>>> :xmode verbose

:config KEY [VALUE]¶

Get or set REPL configuration. Settings are stored in ~/.run_repl_config and apply across restarts.

Supported keys:

Usage¶

>>> :config
detect  on
xmode   verbose

>>> :config detect
on

>>> :config xmode plain
[xmode = plain]

>>> :config detect off
[detect = off]

:paste and :end¶

Paste multi-line code (e.g. from a doc or website) without the REPL treating each line as a separate command. Leading >>> and ... prompts are stripped, and the block is dedented before execution.

You can also press Ctrl-D (EOF) to execute the buffer and then exit the REPL.

Usage¶

>>> :paste
[paste mode — type :end or Ctrl-D to execute]
>>> 1+1
>>> 2+2
>>> :end
2
4
[paste done]

Pasted lines can include >>> or ... at the start; they are removed before execution.

:precision [N]¶

Control float display precision when the REPL shows a "last result" (e.g. formatted output). Only affects run’s formatted display, not raw stdout from the language.

You can also set it via :config precision N.

Usage¶

>>> :precision
precision: (default)

>>> :precision 4
[precision = 4]

>>> :precision
precision: 4

:macro and :time¶

:macro <NAME> <range>...¶

Save a history range as a named macro. Ranges use the same syntax as :history (e.g. 4-7, -2, 4-, -6). Run the macro with :macro run NAME or :run NAME (if the name is not a file path).

:time <code>¶

Run the given code once and print the elapsed time.

:who / :whos [pattern]¶

• :who — List names tracked in the current session (variables/functions from executed code).
• :whos [pattern] — Like :who with an optional substring filter on names.

:load <path>¶

Load and execute a file or http(s) URL in the current REPL session. URLs are fetched to a temp file, then loaded like a local file. Variables, functions, and classes defined in the file persist in the session — you can use them immediately after loading. For languages with session support (Python, JavaScript), the file contents are fed through the session evaluator. Tab completion for file paths is available.

:run <name> — Same as :load for a path or URL. If name is a macro you defined with :macro, it runs that macro instead.

Usage¶

>>> :load <file_path>
>>> :load https://example.com/script.py
>>> :run mymacro

Parameters¶

• <file_path> — Path to file (relative or absolute) or http(s) URL

Examples¶

Python file:

def add(a, b):
    return a + b

def multiply(a, b):
    return a * b

PI = 3.14159

>>> :py
python>>> :load helpers.py

python>>> add(10, 5)
15

python>>> multiply(3, 4)
12

python>>> PI
3.14159

JavaScript file:

function greet(name) {
    return `Hello, ${name}!`;
}

const VERSION = '1.0.0';

>>> :js
javascript>>> :load utils.js

javascript>>> greet('Alice')
'Hello, Alice!'

javascript>>> VERSION
'1.0.0'

Relative vs Absolute Paths¶

# Relative to current directory
>>> :load ./scripts/helper.py
>>> :load ../utils.js

# Absolute path
>>> :load /home/user/scripts/helper.py
>>> :load C:\Users\user\scripts\helper.py  # Windows

Loading Multiple Files¶

python>>> :load config.py
python>>> :load database.py
python>>> :load models.py
# All loaded in order

Use Cases¶

1. Load utility functions
2. Import configurations
3. Test modules in development
4. Load data processing scripts

:save <path>¶

Save all session history (commands you've entered) to a file. Useful for capturing an interactive session as a reusable script.

Usage¶

>>> :save <file_path>

Parameters¶

• <file_path> - Path to save the history to (relative or absolute)

Examples¶

python>>> x = 10
python>>> y = 20
python>>> print(x + y)
30

python>>> :save session.py
[saved 3 entries to session.py]

The saved file contains your code:

x = 10
y = 20
print(x + y)

Use Cases¶

1. Capture exploratory work as a reusable script
2. Save debugging sessions for later reference
3. Export REPL experiments to proper source files

:history [n|range]¶

Show recent command history. Defaults to the last 25 entries. Supports ranges and options:

• n — Last n entries (default 25).
• 4-6 — Range (entries 4 to 6). 4- — From 4 to end. -6 — Last 6.
• -g PATTERN — Grep history for lines matching PATTERN.
• -f FILE — Append selected history to FILE (ranges optional; default last 25).

Usage¶

>>> :history           # Show last 25 entries
>>> :history 10        # Show last 10 entries
>>> :history 4-6       # Show entries 4–6
>>> :history -g print  # Grep for "print"
>>> :history -f out.py # Append last 25 to out.py

Parameters¶

• [n] — Optional number of entries (default: 25), or range (4-6, 4-, -6), or -g PATTERN, or -f FILE

Example¶

python>>> x = 10
python>>> y = 20
python>>> x + y
30

python>>> :history
[   1] x = 10
[   2] y = 20
[   3] x + y

Multi-line entries are shown with a continuation indicator:

python>>> :history
[   1] def fib(n): (...)
[   2] fib(10)

:install <pkg>¶

Install a package using the current language's native package manager. Delegates to python -m pip, npm, gem, cargo, etc. based on the active language. For Python, this uses whichever python is on your PATH, so virtual environments are respected (activate your venv first).

Usage¶

>>> :install <package_name>

Parameters¶

• <package_name> - The package to install

Examples¶

Python (uses pip via python -m pip):

python>>> :install requests
[run] Installing 'requests' for python...
[run] Successfully installed 'requests'

python>>> import requests
python>>> requests.get('https://httpbin.org/get').status_code
200

JavaScript (uses npm):

javascript>>> :install lodash
[run] Installing 'lodash' for javascript...
[run] Successfully installed 'lodash'

Ruby (uses gem):

ruby>>> :install nokogiri
[run] Installing 'nokogiri' for ruby...
[run] Successfully installed 'nokogiri'

Supported Package Managers¶

Custom Package Managers¶

You can override the install command per language with an environment variable:

# Use uv instead of pip
export RUN_INSTALL_COMMAND_PYTHON="uv pip install {package}"

# Use pnpm instead of npm
export RUN_INSTALL_COMMAND_JAVASCRIPT="pnpm add {package}"

{package} will be replaced with the package name. If you omit it, the package name is appended automatically.

CLI Alternative¶

You can also install packages from the command line without entering the REPL:

run --install numpy -l python
run --install lodash -l js
run --install nokogiri -l ruby

:bench [N] <code>¶

Benchmark a code snippet by running it N times and reporting statistics.

Usage¶

>>> :bench print('hello')          # Default: 10 iterations
>>> :bench 20 print('hello')       # Run 20 times

Parameters¶

• [N] - Optional iteration count (default: 10, minimum: 1)
• <code> - Code to benchmark

Example¶

python>>> :bench 10 sum(range(100000))
Benchmark: 10 iterations
  warmup: 12ms
  run 1: 10.24ms
  run 2: 9.87ms
  ...
Results (10 runs):
  min:    9.12ms
  max:    12.45ms
  avg:    10.15ms
  median: 10.02ms
  stddev: 0.89ms

Output¶

• warmup — First run (not counted) to prime caches
• min/max/avg/median — Distribution of execution times
• stddev — Standard deviation across all runs

:type / :which¶

Show the active language and whether a session is currently open.

Usage¶

>>> :type
>>> :which

Example¶

python>>> :type
Active language: python (session active)

>>> :which
Active language: python (no session)

:reset¶

Clear all state in the current language session. Variables, functions, and imports are discarded.

Usage¶

>>> :reset

Example¶

python>>> x = 100
python>>> y = 200
python>>> import math

python>>> x + y
300

python>>> :reset
session for 'python' reset

python>>> x
NameError: name 'x' is not defined

python>>> math.pi
NameError: name 'math' is not defined

When to Use¶

• Start fresh without restarting REPL
• Clear accumulated state
• Fix issues from previous commands
• Memory cleanup for long sessions

Language-Specific Behavior¶

Different languages handle reset differently:

Python:

python>>> x = 10
python>>> :reset
# Clears all variables and imports

JavaScript:

javascript>>> let x = 10
javascript>>> :reset
# Clears all variables and functions

Compiled (Rust/C/C++):

rust>>> let x = 10;
rust>>> :reset
# Clears accumulated code

:exit / :quit¶

Exit the REPL and return to the shell.

Usage¶

>>> :exit
# or
>>> :quit

Example¶

>>> :exit
Goodbye!
$

Alternative Methods¶

Keyboard shortcuts: - Unix/Linux/macOS: Ctrl+D - Windows: Ctrl+Z then Enter

Using commands:

>>> :quit
Goodbye!

:last¶

Print the stdout from the last code execution. Useful after running a snippet to re-examine its output without re-executing.

Usage¶

>>> :last

Example¶

python>>> :last
(no last output)

python>>> 1 + 1
2

python>>> :last
2

Numbered Prompts¶

Enable numbered prompts to show an [n] counter in the prompt, similar to IPython's In[n] style. The counter increments with each executed snippet.

Usage¶

>>> :config numbered_prompts on
>>> :config numbered_prompts off

Example¶

>>> :config numbered_prompts on
[numbered_prompts = on]

python [1]>>> 1 + 1
2
python [2]>>> x = 42
python [3]>>> x
42

The setting persists across restarts via ~/.run_repl_config.

_ (Underscore — Last Expression Result)¶

In languages that support it (currently Python), the special variable _ is set to the result of the last expression. This mirrors Python's interactive interpreter behavior.

Example¶

python>>> 2 + 3
5
python>>> _ * 10
50

:? EXPR — Introspection¶

Show documentation or source for a name. In Python sessions, this runs help(expr). For other languages, introspection prints "not available".

Usage¶

>>> :? <name>

Parameters¶

• <name> — A valid identifier (letters, digits, dots, underscores). E.g. print, os.path, str.split.

Example¶

python>>> :? print
Help on built-in function print in module builtins:

print(*args, sep=' ', end='\n', file=None, flush=False)
    Prints the values to a stream, or to sys.stdout by default.
    ...

javascript>>> :? console
[run] introspection not available for javascript

:debug [CODE] — Debugger¶

Run the last snippet (or the provided CODE) under the language's debugger. Currently supported for Python (uses pdb). Other languages print "Debug not available".

Usage¶

>>> :debug            # Debug last snippet
>>> :debug <code>     # Debug specific code

Example¶

python>>> def buggy():
...         x = 1 / 0
python>>> :debug buggy()
> /tmp/run_debug.py(1)<module>()
-> buggy()
(Pdb)

javascript>>> :debug 1+1
[run] Debug not available for javascript

Command Aliases¶

Many commands have shorter aliases:

Tips & Best Practices¶

1. Use Shortcuts for Speed¶

# Faster
>>> :py
>>> :js
>>> :go

# Slower
>>> :lang python
>>> :lang javascript
>>> :lang go

2. Check Supported Languages¶

Check what languages run supports:

>>> :languages
# See all supported languages

3. Load Common Utilities¶

Create a personal utilities file:

import json
import sys
import os
import re

def jprint(data):
    print(json.dumps(data, indent=2))

def read_json(path):
    with open(path) as f:
        return json.load(f)

python>>> :load ~/.run_helpers.py
python>>> jprint({'name': 'Alice', 'age': 30})
{
  "name": "Alice",
  "age": 30
}

4. Reset on Errors¶

If something breaks:

python>>> # Oops, something went wrong
python>>> :reset
python>>> # Start fresh

5. Use :help as Reference¶

Forget a command?

>>> :help
# Quick reference

Piping Code (Not REPL)¶

When stdin is piped, run executes it as a single script (not an interactive REPL). REPL commands like :py and :exit only work in interactive sessions.

echo -e "x = 10\ny = 20\nprint(x + y)" | run --lang python -

Error Handling¶

Unknown Command¶

>>> :unknown
Error: Unknown command: unknown
Type :help for available commands.

Missing Argument¶

>>> :lang
Error: :lang requires a language name
Usage: :lang <language>

>>> :load
Error: :load requires a file path
Usage: :load <path>

Language Not Found¶

>>> :lang nonexistent
Error: Language 'nonexistent' not found
Use :languages to see available languages

File Not Found¶

>>> :load missing.py
Error: File not found: missing.py

Next Steps¶

Stateful Sessions → Language-Specific Behavior →