xclog Reference (iOS Console Capture)
Reference for xclog, the console capture tool bundled with Axiom. It merges simctl launch --console output (print, debugPrint, NSLog) with log stream --style json output (os_log, Logger) into one JSON stream your assistant can read, and it can search recent logs on a connected iPhone or iPad.
When to Use This Reference
Use this reference when:
- Looking up the flags and behavior of the
list,launch,attach, andshowsubcommands - Checking which Swift logging APIs each subcommand captures
- Reading the JSON output schema (
time,source,level,subsystem,category,process,pid,text) - Configuring
--timeout,--max-lines,--filter,--subsystem,--output,--human, or--no-color - Targeting a specific simulator with
--device <udid>or a physical device with--device-udid <udid> - Reading or writing
.axiom/preferences.yaml, which saves the simulator and bundle ID between sessions - Understanding why
attachskipsprint()output (it streamsos_logonly) - Diagnosing common errors (bad bundle ID, no booted simulator, invalid regex, invalid subsystem, a log stream that dies mid-capture)
Example Prompts
Questions you can ask your assistant that will draw from this reference:
- "What flags does
xclog launchaccept?" - "What's the JSON schema xclog emits?"
- "Can xclog read logs from a physical device?"
- "How do I capture only errors from my app's subsystem?"
- "How does the
.axiom/preferences.yamlfile work?" - "Why doesn't
xclog attachshow myprint()output?" - "How do I cap the output so it doesn't flood my assistant's context?"
What's Covered
- Invocation – In Claude Code,
xclogis on yourPATHbecause Axiom's session hook adds the plugin'stools/folder; if the bare name isn't found,<plugin-root>/tools/xclogworks, where<plugin-root>is the installed plugin's folder. Codex runs<plugin-root>/tools/xclog(there, the folder containing.codex-plugin/plugin.json) unlesscommand -v xclogfinds it onPATH. In Pi,xclogisn't on yourPATHuntil you add it (Pi setup). MCP clients callaxiom_xclog_launch,axiom_xclog_attach,axiom_xclog_show, andaxiom_xclog_list, and a table maps each subcommand and flag to the tool's inputs - MCP limits – Each tool call blocks until it returns.
launchandattachget a 30-second timeout when you set no bound, and every call ends at 120 seconds. Results are JSON only, andattachcan't write to a file listsubcommand – Discovers installed apps, as JSON lines (bundle_id,name,version)launchsubcommand – Full capture (print,debugPrint,NSLog,os_log,Logger), simulator only; terminates any running instance of the app firstattachsubcommand – Monitors an already-running process throughos_logonly, simulator only; preserves app state but captures noprint()outputshowsubcommand – Searches recent logs on a simulator or a physical device (for a device, it runslog collectover USB; the device must be connected and unlocked)- JSON output schema –
time,source(print,stderr,os_log),level(debug,default,info,error,fault),subsystem,category,process,pid,text; fields that don't apply are omitted, not null - Human-readable mode –
--human, plus--no-color - Options reference table –
--device,--device-udid,--output,--human,--no-color,--filter,--subsystem,--max-lines,--timeout,--last - Coverage tables – Swift API by subcommand (
print,debugPrint,NSLog,os_log,Logger) and subcommand by platform (simulator or physical device) - Preferences file – The
.axiom/preferences.yamlschema (simulator.device,deviceUDID,bundleId), when to read and write it, and adding.axiom/to.gitignore - Filtering –
--filtermatches message text with a Go regular expression; filtering by level or another JSON field needsjq - Common subsystems –
com.apple.network,com.apple.coredata,com.apple.swiftui,com.apple.uikit - Errors – xclog writes errors to stderr and exits with code 1, or 2 for a flag it can't parse; a table lists the common messages and their fixes
- Workflows – Step-by-step command sequences for a runtime crash and a silent failure
Documentation Scope
This page documents the xclog-ref skill in the axiom-tools suite. xclog is Axiom's bundled tool for live console capture.
- For when to reach for console capture and how it fits a debugging session, see Console Capture (xclog)
Related
- /axiom:console – The command that runs a guided xclog capture for you
- Crash Symbolication (xcsym) – The after-the-fact counterpart: xcsym reads a crash report, while xclog captures logs as they happen
- Xcode Debugging – Environment-first checks to run when the app won't build or launch at all
- xcprof-ref, xcsym-ref, and xcui-ref – References for the other bundled tools; the Tools overview covers axbuild and xcproject