CLI Reference

Complete reference for every ada subcommand, flag, and output format.

ada capture

Start and stop multimodal capture sessions. Sessions are stored in ~/.ada/sessions/<session_id>/.

capture start

ada capture start <binary> [options] [-- args...]

Flag	Default	Description
`--no-screen`	(off)	Disable screen recording (enabled by default)
`--no-voice`	(off)	Disable voice recording (enabled by default)
`--pre-roll-ms`	`0`	Detail pre-roll in ms (flight recorder)
`--post-roll-ms`	`0`	Detail post-roll in ms (flight recorder)
`--with-detail`	(off)	Enable detail lane capture (register values) without voice recording

The <binary> argument accepts a direct path to an executable or a .app bundle path (automatically resolves to Contents/MacOS/<executable>).

capture stop

ada capture stop [--session-id <id>]

Flag	Default	Description
`--session-id`	(latest running)	Session ID to stop

ada query

Query captured session data — traces, transcripts, screenshots, and metadata.

ada query <bundle> <subcommand> [options]

The <bundle> argument accepts:

@latest — the most recent session
Session ID — e.g. session_2026_01_24_14_56_19_a1b2c3
Bundle path — direct path to a session directory or .adabundle

query summary

Show session summary statistics.

ada query @latest summary [-f text|json]

Flag	Short	Default	Description
`--format`	`-f`	`text`	Output format (text or json)

query events

List trace events with optional filters.

ada query @latest events [options]

Flag	Short	Default	Description
`--thread`	`-t`	(all)	Filter by thread ID
`--function`		(none)	Filter by function name (substring match)
`--limit`	`-l`	`1000`	Maximum events to return
`--offset`	`-o`	`0`	Number of events to skip
`--since-ns`		(none)	Timestamp lower bound (nanoseconds)
`--until-ns`		(none)	Timestamp upper bound (nanoseconds)
`--with-values`		(off)	Include register values (x0-x7) from ATF detail lane
`--format`	`-f`	`text`	Output format (`text`, `json`, `line`, or `chrome-trace`)

query timeline

Show multi-thread interleaved timeline with call depth visualization.

ada query @latest timeline [options]

Flag	Short	Default	Description
`--thread`	`-t`	(none)	Filter by thread ID
`--function`		(none)	Filter by function name (substring match)
`--limit`	`-l`	`10000`	Maximum number of events to return
`--since-ns`		(none)	Timestamp lower bound (nanoseconds)
`--until-ns`		(none)	Timestamp upper bound (nanoseconds)
`--with-values`		(off)	Include register values (x0-x7) from ATF detail lane
`--format`	`-f`	`dtrace-flowindent`	Output format (`dtrace-flowindent`, `json`, or `line`)

query reverse

Reverse-trace matched functions newest-to-oldest (rr-style).

ada query @latest reverse <function_pattern> [options]

Flag	Short	Default	Description
`--thread`	`-t`	(none)	Filter by thread ID
`--limit`	`-l`	`1000`	Maximum number of matching events to return
`--since-ns`		(none)	Timestamp lower bound (nanoseconds)
`--until-ns`		(none)	Timestamp upper bound (nanoseconds)
`--with-values`		`true`	Include register values (x0-x7) — enabled by default for reverse
`--format`	`-f`	`text`	Output format (`text`, `json`, or `line`)

query functions

List all traced functions with their IDs.

ada query @latest functions [-f text|json]

Flag	Short	Default	Description
`--format`	`-f`	`text`	Output format (text or json)

query threads

List all traced threads.

ada query @latest threads [-f text|json]

Flag	Short	Default	Description
`--format`	`-f`	`text`	Output format (text or json)

query calls

Find calls to a specific function (substring match).

ada query @latest calls "viewDidLoad" [options]

Flag	Short	Default	Description
`--limit`	`-l`	`1000`	Maximum number of results
`--format`	`-f`	`text`	Output format (`text`, `json`, `line`, or `chrome-trace`)

query time-info

Show session time bounds and duration.

ada query @latest time-info [-f text|json]

query capabilities

Show available query capabilities and tool requirements.

ada query @latest capabilities [-f text|json]

query transcribe info

Get voice transcript metadata without loading the full content.

ada query @latest transcribe info [-f text|json]

Flag	Short	Default	Description
`--format`	`-f`	`text`	Output format (text or json)

query transcribe words

Get word-level timestamps for a time range.

ada query @latest transcribe words [options]

Flag	Short	Default	Description
`--since`		(none)	Start time in seconds
`--until`		(none)	End time in seconds
`--format`	`-f`	`text`	Output format (text or json)

query transcribe segments

Get transcript segments with pagination.

ada query @latest transcribe segments [options]

Flag	Short	Default	Description
`--offset`	`-o`	`0`	Segments to skip
`--limit`	`-l`	`20`	Maximum segments to return
`--since`		(none)	Filter by start time (seconds)
`--until`		(none)	Filter by end time (seconds)
`--format`	`-f`	`text`	Output format (`text`, `json`)

query screenshot

Extract a screenshot from the screen recording.

ada query @latest screenshot --time 15.5 [--output /tmp/screen.png]

Flag	Short	Default	Description
`--time`	`-t`	(none)	Time in seconds to extract a single frame from
`--from`		(none)	Start time in seconds for range extraction
`--to`		(none)	End time in seconds for range extraction
`--every`		`1`	Extract every Nth frame in range mode (default: all frames)
`--output`	`-o`	(none)	Output file path (single mode) or directory (range mode)
`--format`	`-f`	`text`	Output format (text or json)

query video-info

Show screen recording video info (fps, frame count, codec).

ada query @latest video-info [-f text|json]

Flag	Short	Default	Description
`--format`	`-f`	`text`	Output format (text or json)

ada session

Manage ADA capture sessions.

session list

ada session list [options]

Flag	Short	Default	Description
`--running`		(off)	Show only running sessions
`--app`		(none)	Filter by app name
`--format`	`-f`	`text`	Output format (`text`, `json`)

session latest

Print the bundle path for the most recent session.

ada session latest [--running]

Flag	Default	Description
`--running`	(off)	Show latest running session only

session cleanup

Mark orphaned sessions (process no longer alive) as failed.

ada session cleanup

ada doctor

Check system health and dependencies.

doctor check

ada doctor check [-f text|json]

Flag	Short	Default	Description
`--format`	`-f`	`text`	Output format (text or json)

Checks: Frida agent library, whisper-cli, ffmpeg. Exits with code 1 if any check fails.

ada trace

Lower-level trace management commands. These are used internally by ada capture and are useful for advanced workflows.

trace start

ada trace start <binary> [-o ./traces] [args...]

Flag	Short	Default	Description
`--output`	`-o`	`./traces`	Output directory for trace files

trace start-xcode

ada trace start-xcode <project> -s <scheme> [-o ./traces]

Flag	Short	Default	Description
`--scheme`	`-s`	(required)	Xcode scheme to build and run
`--output`	`-o`	`./traces`	Output directory for trace files

trace attach

ada trace attach <pid> [-o ./traces]

Flag	Short	Default	Description
`--output`	`-o`	`./traces`	Output directory for trace files

trace stop

ada trace stop

Prints instructions for stopping a running trace (Ctrl+C or SIGINT).

trace list

ada trace list [directory]

Lists trace sessions in the given directory (default: ./traces).

ada symbols

Symbol resolution and dSYM management. Used internally for resolving function IDs to human-readable names.

symbols resolve

ada symbols resolve <session> <function_id>

Resolve a function_id (hex, e.g. 0x0000001c00000001) to its symbol name, source file, and line number.

symbols locate-dsym

ada symbols locate-dsym <uuid>

Locate the dSYM bundle for a binary by UUID (e.g. 550E8400-E29B-41D4-A716-446655440000).

symbols demangle

ada symbols demangle <name>

Demangle a C++ or Swift symbol name.

symbols dump

ada symbols dump <session> [-f text|json]

Flag	Short	Default	Description
`--format`	`-f`	`text`	Output format (text, json)

Dump all modules and symbols from a session manifest.

symbols info

ada symbols info <session>

Show session symbol summary (format version, module count, symbol count).

ada analysis

Manage analysis sessions.

analysis init

Initialize a new analysis session.

ada analysis init [options]

Flag	Short	Default	Description
`--capture-session`		(none)	Capture session ID to analyze (e.g., session_2026_03_08_20_35_50_13e516)
`--project-path`		(none)	Project path being analyzed
`--format`	`-f`	`text`	Output format (text or json)

Environment Variables

Variable	Description
`ADA_SESSIONS_DIR`	Session storage root (default: `~/.ada/sessions`)
`ADA_AGENT_RPATH_SEARCH_PATHS`	Colon-separated paths for `libfrida_agent.dylib` lookup
`ADA_WHISPER_PATH`	Override path to `whisper-cli`
`ADA_FFMPEG_PATH`	Override path to `ffmpeg`
`RUST_LOG`	Logging verbosity (e.g. `info`, `debug`, `trace`)

Global Flags

Flag	Short	Description
`--verbose`	`-v`	Enable verbose output
`--version`		Print version
`--help`	`-h`	Print help

Output Formats

Where supported, --format (-f) accepts:

text (default) — human-readable output
json — structured JSON for programmatic use
line — one entry per line (events and calls only)