Reference

All Options

All project and document options are set under extensions: term: — in _quarto.yml for project-wide defaults, or in a document’s front matter to override per file. Cell options use #| at the top of a cell. Line options use the marker (default #!) at the end of a line.

Option	Project	Document	Cell	Line	Default	Description
assert			x	x	(none)	Regex/substring pattern to validate in output
cache	x	x			true	Cache results to skip re-execution on unchanged inputs
strip-auto-indent	x	x			false	Counteract REPL auto-indentation on continuation lines (for Python PyREPL, Ruby irb)
callout			x		[]	Line specs to annotate with callout markers
callout-values			x		"123456789"	Characters or list of strings for callout labels
callout-format			x		"<{}>"	Format template; {} is replaced with the value
delay	x	x	x	x	0.1	Seconds to wait before executing a line
docker	x	x			(none)	Run commands in a Docker container (see Docker)
echo	x	x	x		terminal	Output mode: terminal, source, true, or false
enter			x	x	(from literal)	Press Enter after the line
env	x	x			{}	Additional environment variables
eval			x		true	Execute the cell; false renders it as a static code block
expect-prompt			x	x	(from enter)	Wait for prompt after the line
fullscreen			x		false	Capture the entire terminal screen
highlight	x	x	x		bash	Syntax highlighting language (for echo: source)
hold	x	x	x	x	0.0 (doc/cell), 0.1 (line)	Seconds to wait after execution (captures ongoing output)
include			x		true	Execute the cell but hide it entirely from output
init	x	x			(none)	Script(s) or command(s) to run at session start
keep-last-prompt	x	x	x		false	Keep the trailing prompt in output
label			x		(none)	Cell label (shown in verbose mode)
literal			x	x	true	Send text as typed characters; false for key names
marker	x	x	x		#!	Prefix for line option annotations
output			x		true	Show terminal output
profile	x	x			(none)	Shell preset: zsh, bash, python, node, r, ruby, sqlite, duckdb, fish, nushell, sh
prompt	x	x			$	Literal prompt string (auto-sets PS1). Alias: ps1
prompt-regex	x	x			(derived)	Raw regex override for prompt detection. Alias: ps1-regex
ps2	x	x			(derived)	Literal continuation prompt string
ps2-regex	x	x			(derived from ps2)	Raw regex override for continuation prompt detection
record	x	x			(none)	File path(s) to record session (.cast or .termshow)
remove			x		[]	Line specs to remove from output (indices, ranges, or regex)
scroll			x		!fullscreen	Include scrollback in capture
shell	x	x			zsh	Shell to use
source			x		(none)	Import cell code from an external file
shell-args	x	x			(auto)	Shell arguments
spacing	x	x	x		false	Add blank lines between commands in output
timeout	x	x	x	x	10.0	Seconds to wait for prompt before error
truncate			x		[]	Line specs to truncate (replaced with “[N lines truncated]” message)
typing	x	x	x	x	false	Human typing simulation
verbose	x	x			false	Print execution details to stderr

Style Options

Style options live under style: and control visual appearance. They support format-specific overrides and per-cell overrides. See the Styling page for full details, colorscheme gallery, and examples.

Option	Project	Document	Cell	Default	Description
chrome	x	x	x	false	macOS-style window chrome (traffic light dots); string value becomes title
colorscheme	x	x	x	(none)	Colorscheme name
colorscheme-light	x	x	x	(none)	Colorscheme for light mode
colorscheme-dark	x	x	x	(none)	Colorscheme for dark mode
font-family	x	x	x	(none)	Font family for terminal output
font-size	x	x	x	(none)	Font size (e.g., 0.85em)
line-height	x	x	x	(none)	Line height (e.g., 1.2)
ansi	x	x	x	true	Render ANSI colors in output
spacing	x	x	x	false	Add blank lines between commands in output
trailing-spaces	x	x	x	false	Preserve trailing whitespace in output
cols	x	x		80	Terminal width in columns
rows	x	x		24	Terminal height in rows

Document-Level Options

Set these under extensions: term: in your YAML front matter:

Option	Default	Description
profile	(none)	Shell preset: zsh, bash, python, node, r, ruby, sqlite, duckdb, fish, nushell, sh (see Shells)
strip-auto-indent	false	Counteract REPL auto-indentation on continuation lines (for Python PyREPL, Ruby irb)
shell	zsh	Shell to use
shell-args	auto	Shell arguments (defaults: --no-rcs for zsh, --norc --noprofile for bash)
prompt	$	Literal prompt string. Auto-sets PS1 and builds the matching regex. Alias: ps1
prompt-regex	(derived)	Raw regex override for prompt detection. Alias: ps1-regex
ps2	(derived)	Literal continuation prompt string
ps2-regex	(derived from ps2)	Raw regex for continuation prompt (e.g., "^\\s*$" for fish)
timeout	10.0	Seconds to wait for prompt before error
delay	0.1	Default seconds to wait before executing each line
hold	0.0	Default seconds to wait after each cell completes
echo	terminal	Default output mode for cells
keep-last-prompt	false	Default: keep trailing prompt in cell output
highlight	bash	Default syntax highlighting language for echo: source cells
marker	#!	Prefix for line option annotations
typing	false	Human typing simulation (see below)
record	(none)	File path to record session (.cast or .termshow)
verbose	false	Print execution details to stderr
init	(none)	Script(s) or command(s) to run at session start (string or list)
env	{}	Additional environment variables
docker	(none)	Run commands in a Docker container (see Docker)
style	(none)	Style options (see Styling)

Cell Options

Set these with #| at the top of a cell:

Option	Default	Description
assert	(none)	Regex or substring pattern; fails if not found in cell output
eval	true	Execute the cell; false renders it as a static code block
include	true	Execute the cell but hide it entirely from output
label	(none)	Cell label (shown in verbose mode)
echo	(from config)	Output mode: terminal, source, true, or false
output	true	Show terminal output
fullscreen	false	Capture the entire terminal screen
scroll	!fullscreen	Include scrollback in capture
keep-last-prompt	(from config)	Keep the trailing prompt in output
spacing	(from config)	Override spacing for this cell
typing	(from config)	Override typing simulation
timeout	(from config)	Override timeout for this cell
hold	(from config)	Seconds to wait after cell completes (captures ongoing output)
literal	true	Default literal for all lines in this cell
delay	(from config)	Default delay for all lines in this cell
enter	(from literal)	Default enter for all lines in this cell
expect-prompt	(from enter)	Default expect-prompt for all lines in this cell
highlight	(from config)	Syntax highlighting language (for echo: source)
marker	(from config)	Override line marker for this cell
remove	[]	Line specs to remove from output
source	(none)	Import cell code from an external file path
truncate	[]	Line specs to truncate (replaced with “[N lines truncated]” message)
callout	[]	Line specs for callout annotations
callout-values	"123456789"	Characters or list of strings for callout labels
callout-format	"<{}>"	Format template; {} is replaced with the value
style	(from config)	Override style options for this cell (see Styling)

Display Controls

The eval, echo, output, and include options interact to control what the user sees:

eval	echo	output	include	Result
true	terminal	true	true	Full terminal output (default)
true	source	true	true	Source code block + terminal output
true	source	false	true	Source code block only
true	false	true	true	Terminal output without commands
true	false	false	true	Nothing visible (but cell executes)
true	any	any	false	Nothing visible (but cell executes)
false	—	—	—	Static code block (no execution)

Common patterns:

• Show only output: echo: false
• Show only source: echo: source, output: false
• Execute silently (e.g., setup): include: false
• Static example (no execution): eval: false

Note: include: false is a shortcut that sets both echo: false and output: false.

Line Options

Each line in a {term} cell is sent to the shell individually. Line options control how each line is delivered: whether it’s typed as literal characters or interpreted as a key name, whether Enter is pressed, and timing. See Recipes for worked examples.

Append options to any line using the marker (default #!):

sleep 100 #! expect-prompt: false
ctrl-c #! literal: false, delay: 0.5

Option	Default	Description
assert	(none)	Regex or substring pattern; fails if not found in output after this line
literal	true	Send text as typed characters. Set to false for key names.
enter	(from cell/literal)	Press Enter after the line
expect-prompt	(from cell/enter)	Wait for prompt after the line
delay	(from cell)	Seconds to wait before executing this line
hold	0.1	Seconds to wait after executing (captures output)
timeout	(from cell/config)	Seconds to wait for prompt after this line
typing	(from cell/config)	Enable/disable typing simulation for this line (true/false)

Line Specs

The remove, truncate, and callout options accept a list of line specs that identify lines in the rendered output (input + output combined). Line numbers refer to the original output before any removals or truncations.

Format	Example	Description
Integer	3	Line 3 (1-indexed)
Negative integer	-1	Last line, -2 second-to-last, etc.
Range	"3:7"	Lines 3 through 7 (inclusive)
Open start	":5"	First 5 lines (lines 1-5)
Open end	"5:"	From line 5 to the end
Negative range	"-3:"	Last 3 lines
Regex	"error"	Lines matching the pattern

Values are comma-separated:

#| truncate: 3:7
#| remove: :2, -1
#| callout: 1, -1

Use bracket syntax when a regex contains a comma: #| remove: ["foo,bar"].

For truncate, removed lines are replaced with an italic “[N lines truncated]” message. Consecutive truncated lines are grouped into a single message.

Special Keys

When literal: false, these key names are recognized:

Key	Aliases
enter	return, cr
tab
space
escape	esc
backspace	bs
delete	del
up, down, left, right
home, end
page-up	pageup, page_up
page-down	pagedown, page_down
insert
f1 through f12

Any other text is sent as raw bytes (e.g., q sends the letter q without pressing Enter).

Modifier Combinations

All modifier prefixes can be combined in any order:

Prefix	Shorthand	Example
ctrl-	c-	ctrl-c, c-c
shift-	s-	shift-a, s-a
alt-	m-, meta-	alt-a, m-a

Combinations: ctrl-shift-a, ctrl-alt-a, alt-shift-up, ctrl-alt-shift-a.

Human Typing Simulation

Simulate realistic human typing for recordings:

extensions:
  term:
    typing:
      speed: 100        # characters per minute
      error-rate: 0.02  # probability of a typo per character

When a “typo” occurs, the simulated typist hits a QWERTY-adjacent key and then corrects with backspace. Timing follows a log-normal distribution with bigram-aware adjustments.

Disable typing for individual cells with #| typing: false or individual lines with #! typing: false.

Prompt Detection

By default, quarto-term uses the literal prompt value (default $) to detect when a command has finished. It:

1. Sets PS1 to prompt + " " (e.g., $) in the shell environment.
2. Builds a regex from regex::escape(prompt) + "\\s*$" to match the prompt in output.

For advanced use cases, override the regex directly:

extensions:
  term:
    prompt: "myhost>"
    prompt-regex: "(\\$|#|myhost>)\\s*$"

PS2 (continuation prompt) is auto-set to "> " for multi-line command detection.

Init Scripts

Run commands or source scripts at session start using init. Each entry can be a plugin name, a file path, or an inline command:

extensions:
  term:
    init:
      - zsh-syntax-highlighting
      - "setopt INTERACTIVE_COMMENTS"

For plugin names, quarto-term checks the current working directory, then searches common installation paths (/opt/homebrew/share, /usr/local/share, /usr/share, /home/linuxbrew/.linuxbrew/share).

Entries that resolve to a file are sourced; everything else is executed as an inline command. Multi-line blocks are split and run line by line.

Terminal Recordings

Record your session for playback:

extensions:
  term:
    record: "session.cast"

Supported formats (detected by file extension):

• .cast — asciicast v2 format, playable with asciinema
• .termshow — termshow format, works with the termshow player

You can record to multiple files simultaneously:

extensions:
  term:
    record:
      - "session.cast"
      - "session.termshow"

Output Formats

Format	Style support	Notes
HTML	Full	All style options, ANSI colors as styled spans
RevealJS	Full	Same as HTML with CSS specificity overrides
PDF (LaTeX)	Full	tcolorbox with colored text, fontspec for fonts
PDF (Typst)	Full	Styled block with colored text runs
EPUB	Full	Same as HTML (EPUB uses XHTML)
Markdown/GFM	Text only	Plain text in fenced code blocks (no styling)

Use format-specific style overrides to optimize appearance for each output.