| name | cli-reference |
| description | Canonical reference for the human-facing axci command-line interface. Covers every command and option with its short form, long form, type, default, and effect, the MCP tool each command maps to, its failure modes, and how the CLI path diverges from the MCP path. Use when a user asks what an axci command or option does, or when the MCP server is unavailable and the user must be told what to run by hand. |
| user-invocable | false |
CLI reference
The axci CLI is a HUMAN-FACING tool. You MUST never invoke it. Print the command, ask the user to run it, and
ask them to paste the output back.
The one exemption is --help. axci --help and axci COMMAND --help may be run, and no other axci invocation is
exempt. /communication-mcp-environment-setup owns that exemption.
Scope
Covers:
- The complete
axci command surface: every node, its purpose, and its MCP equivalent
- Every declared option: short form, long form, type, default, required / flag / repeatable status, and effect
- Per-command failure modes, the error each reports, and the exit status it leaves
- How
axci process diverges from the MCP batch path, and why the two report the same fault differently
- What to tell a user to run when the MCP server cannot be restored in this session
Does not cover:
- The MCP batch workflow, lenient sourcing, and resource sizing (see
/log-processing)
- Extraction config authoring, validation, and event-code semantics (see
/extraction-configuration)
- Manifest management, archive assembly, and hardware discovery (see
/microcontroller-setup)
- Diagnosing why the MCP server is down (see
/communication-mcp-environment-setup)
- Driving log processing from Python. Orchestration runs through MCP or this CLI only
Handoff rules: If the user wants an operation performed rather than explained, use the MCP tools and invoke the
owning skill. If the MCP tools are unavailable, invoke /communication-mcp-environment-setup first and fall back to the
CLI-command handoff table below only after the server cannot be restored.
Agent requirements
You MUST answer CLI questions from this skill or from axci --help, never from memory. When a user's report disagrees
with this reference, ask them to run axci COMMAND --help and read the installed build's answer.
Command surface
The CLI declares eight Click nodes: the root group, one subgroup, and six leaf commands. The entry point is axci = "ataraxis_communication_interface.interfaces.cli:axci_cli".
| Node | Kind | Purpose | MCP equivalent |
|---|
axci | group | Entry point. Dispatches to the subcommands and prints the command listing | None, dispatch only |
axci id | command | Discovers connected Arduino/Teensy controllers running ataraxis-micro-controller | list_microcontrollers_tool |
axci mqtt | command | Reports whether an MQTT broker is reachable at a host and port | check_mqtt_broker_tool |
axci config | group | Dispatches the extraction configuration subcommands | None, dispatch only |
axci config create | command | Writes a precursor extraction config from a microcontroller manifest | None, user-run precursor route (write_extraction_config_tool writes a full config) |
axci config show | command | Prints a config's controllers, modules, event codes, and kernel setting | read_extraction_config_tool |
axci process | command | Extracts module and kernel data from ONE log directory's archives | prepare_log_processing_batch_tool + execute_log_processing_jobs_tool (batch) |
axci mcp | command | Starts the MCP server | None, this command IS the server |
Note: Fourteen options are declared across the surface. Click adds --help to every node on top of those. The CLI
leaves help_option_names at its ["--help"] default, so -h is never a help alias. On axci mqtt, -h is bound to
--host and consumes the next token as a hostname. Always quote the long form to a user.
Option reference
Every option below is declared in interfaces/cli.py. "Required" means Click rejects the invocation without it (exit
code 2). Path options carry Click click.Path constraints, listed under Effect.
axci id
| Short | Long | Type | Default | Form | Effect |
|---|
-b | --baudrate | int | 115200 | optional | Identification baudrate. Used only by UART controllers. Ignored by USB controllers |
Note: 115200 is the option default, not a universal board default. A UART board flashed at another speed reports
[No microcontroller] at the wrong baudrate rather than failing. /microcontroller:firmware-module, "Serial speed",
owns the contract these rates form with the PC, and /platformio-config owns the per-board monitor_speed values.
axci mqtt
| Short | Long | Type | Default | Form | Effect |
|---|
-h | --host | str | "127.0.0.1" | optional | IP address or hostname of the MQTT broker |
-p | --port | int | 1883 | optional | Socket port the MQTT broker listens on |
axci config create
| Short | Long | Type | Default | Form | Effect |
|---|
-m | --manifest-path | Path | (required) | required | The microcontroller_manifest.yaml to read. Must exist and be a readable file |
-o | --output-path | Path | (required) | required | The .yaml file to write. Need not exist. Parents are created automatically |
axci config show
| Short | Long | Type | Default | Form | Effect |
|---|
-c | --config-path | Path | (required) | required | The extraction config .yaml to print. Must exist and be readable |
axci process
| Short | Long | Type | Default | Form | Effect |
|---|
-ld | --log-directory | Path | (required) | required | The ONE DataLogger output directory to search recursively for .npz archives. Must exist and be a readable directory |
-od | --output-directory | Path | (required) | required | The output root. A microcontroller_data/ subdirectory is created under it and holds every feather file and the tracker |
-c | --config | Path | (required) | required | The extraction config .yaml. Must exist and be a readable file |
-id | --job-id | str | None | optional | Runs ONLY the job whose canonical hexadecimal identifier matches. External single-job dispatch. Suppresses -s |
-s | --specifier | str | () | repeatable | A controller ID to process. Repeat once per controller. When omitted, every controller the config declares is processed. Ignored when -id is set |
-w | --workers | int | -1 | optional | The workers ONE job receives, not a batch width. See the note below |
-np | --no-progress | flag | False | flag | Suppresses the extraction progress bar. Bars are displayed by default |
Note: -c expands to --config here but to --config-path on axci config show. The short form is safe to quote
to a user for either command. The long forms are not interchangeable.
Note on -w: The value is a width the job runs at, and the library caps it against nothing. A non-positive value
(the -1 default) resolves the width from each archive in turn, which yields a single worker below the library's
parallel extraction threshold and CONTROLLER_EXTRACTION_JOB_CORES, the declared per-job allocation, at or above it. A
positive value is passed through verbatim to every job, above the declared allocation and above the host's own core
count alike, so a user who names one owns the oversubscription it buys. -w 1 makes every job sequential. The command's
own --help prints the declared allocation as a concrete figure. Read it from there rather than from this skill.
Note on -id: A job identifier is CONTROLLER_EXTRACTION_JOB_NAME hashed together with the controller's
source_id, so one controller keeps the same identifier in every recording. A user obtains it from the job_id key of
a prepare_log_processing_batch_tool job entry, or from the tracker YAML. The identifier is resolved against the
extraction config, not against the archives on disk, so a missing sibling archive cannot mask it.
axci mcp
| Short | Long | Type | Default | Form | Effect |
|---|
-t | --transport | Choice | "stdio" | optional | Transport protocol. Choice of stdio and streamable-http, nothing else |
Note: run_server() also accepts a third value, sse, but the CLI Choice rejects it (exit code 2). Never pass
-t sse, and never tell a user to.
Command behavior and failure modes
Every command wraps its body in a decorator that catches whatever it raises, reports the message at the error level, and
exits 0. A failing command therefore leaves the exit status at 0, so have the user read the reported message rather than
branch a script on it. The console writes to the standard error stream, so a user capturing standard output alone sees
nothing. axci mqtt additionally catches the ConnectionError of an unreachable broker inside its own body. That catch
prints a short remediation line instead of the client's full connection-failure text, and the raw exception names the
host and port too. A malformed invocation exits 2 instead, whether Click rejects the option before any body runs or a
command body raises a usage error the decorator lets pass. A dependency that fails to import fails the axci entry
point with a traceback before Click dispatches anything. The exception names in the tables below are what the bodies
raise, and each reaches the user as that one error line.
axci id
Announces the scan, evaluates every valid serial port through discover_microcontrollers, and prints one numbered line
per port. Each port line reads <n>: <port> -> <description> and closes with [Microcontroller ID: N],
[No microcontroller], or [Connection Failed: <ErrorType>: <text>]. Ports whose USB PID is None are filtered out
before evaluation, which mainly affects Linux hosts, and the evaluation runs in a process pool sized to the smaller of
the port count and the host's worker budget.
The announcement is an INFO line reading Evaluating serial ports at baudrate <baudrate>, this may take a moment.... It
precedes the probing, so it carries no port count and reaches the user before the seconds of scanning it warns about.
| Condition | Behavior |
|---|
| No valid ports | Prints the announcement, then "No valid serial ports detected.", and exits normally. Not an error |
| One port unreachable | Discovery reports the error text in that port's own line, so the sweep over the other ports continues |
| Permission denied on the port | Renders as [Connection Failed]. Check /dev/ttyACM* group membership |
| Wrong UART baudrate | Renders as [No microcontroller]. Retry at the board's own speed before concluding anything |
axci mqtt
Constructs an MQTTCommunication client, connects, reports, and disconnects.
| Condition | Behavior |
|---|
| Broker reachable | Prints a SUCCESS line naming host and port |
| Broker unreachable | Catches the ConnectionError and prints an ERROR line naming the host and port |
| Port at or below 0 | Reports the ValueError the client raises, reading Invalid port number. |
Note: The unreachable message covers every socket-level failure, including a refused connection, a timeout, a
hostname that could not be resolved, and a port number above the socket range. Have the user verify the host string as
well as the broker service.
axci config create
Reads the manifest, emits one controller entry per registered controller with one module entry per registered module,
and writes the result. Every event_codes list is empty and kernel extraction is left unconfigured.
| Condition | Behavior |
|---|
-m missing or not a file | Click rejects the invocation before the command body runs (exit 2) |
| Manifest registers no controllers | ValueError naming the manifest path |
-o does not end in .yaml/.yml | ValueError from the YAML writer |
-o parents do not exist | Created automatically |
-o already exists | Overwritten without a prompt |
Note: The generated file is a precursor, not a usable config. Processing it as written fails inside the job body
with an empty-event-codes error. The user must fill in the event codes, and add a kernel entry if kernel messages are
wanted, before axci process can use it. /extraction-configuration owns the event-code semantics.
axci config show
Prints the config path, then each controller ID, each module as (module_type, module_id): events=[...], and the kernel
line as either its event codes or Kernel: not configured.
| Condition | Behavior |
|---|
-c missing or not a readable file | Click rejects the invocation (exit 2) |
-c does not end in .yaml/.yml | ValueError from the YAML reader |
controllers key carries no value | ValueError from ExtractionConfig.__post_init__ |
Note: show is a printer, not a validator. It reports an empty events=[] without complaint, and it checks nothing
against a manifest. Only validate_extraction_config_tool performs the real checks.
axci process
Drives run_log_processing_pipeline in orchestration/pipeline.py. It resolves the job set with strict sourcing,
echoes the resolved controller IDs, opens the tracker, and runs the jobs one after another.
| Exception | Trigger |
|---|
FileNotFoundError | A requested controller's archive is absent or resolves to more than one file. An archive resolves but cannot be read while the -w -1 default resolves its width. The log directory's tree holds no microcontroller_manifest.yaml. A nonexistent -ld or -c never reaches this path, because Click rejects it with exit code 2 |
ValueError | The tree holds more than one microcontroller_manifest.yaml. A manifest registers no controllers. The config declares no controllers. A requested controller is unregistered in the manifest or absent from the config. -id matches no configured controller. The resolved archives sit in several directories |
ValueError (at job runtime) | A configured module or the kernel declares empty event codes. A controller declares no extraction target at all. The archive carries no onset timestamp message. A logged message's payload size disagrees with its prototype code |
OSError | A directory beneath the log directory cannot be read |
TimeoutError | The tracker's .LOCK file cannot be acquired within the timeout, most often a concurrent MCP batch over the same output directory |
Note: The ValueError for a requested controller unregistered in the manifest or absent from the config, and the
FileNotFoundError archive trigger, are the strict-sourcing counterparts of the MCP path's three skipped_sources
reasons. The absent manifest is not among them, because it raises under either sourcing mode. /log-processing is
authoritative for the lenient model. Cross-reference the Lenient sourcing table in its references/error-routing.md
when a user's hard CLI failure and an agent's silent skip describe the same misconfiguration.
Note: Output layout is identical on both paths, microcontroller_data/ under -od, holding
controller_{source_id}_module_{type}_{id}.feather, controller_{source_id}_kernel.feather, and
microcontroller_processing_tracker.yaml.
axci mcp
| Condition | Behavior |
|---|
-t stdio (default) | Calls console.disable() and prints nothing, because the JSON-RPC stream shares stdout |
-t streamable-http | Echoes Starting AXCI MCP server with streamable-http transport..., then blocks serving HTTP |
| Broken dependency | Traceback from the import, which runs before Click dispatches and so precedes the startup line |
Use streamable-http for any hand-launched smoke test, never the stdio default.
/communication-mcp-environment-setup owns that procedure.
How axci process diverges from the MCP path
These four divergences are the whole reason a user's CLI report can describe behavior the MCP workflow cannot reproduce.
Read them before answering "why did it fail for me but not for you".
| Divergence | CLI behavior | MCP behavior |
|---|
| Strict sourcing | prepare_jobs runs with its strict_sources default, so an unregistered, unconfigured, or unresolvable controller raises and no job runs | prepare_log_processing_batch_tool passes strict_sources=False, records the same three conditions in skipped_sources, and prepares the rest |
| No error recovery | The job loop carries no exception handling. The first job that raises aborts the invocation. The tracker records that one job FAILED, and every job behind it stays SCHEDULED with no failure record of its own and no requeue | The batch engine requeues a broken job, then fails jobs explicitly with a named reason |
| No manifest is fatal | A log directory whose tree holds no microcontroller_manifest.yaml raises FileNotFoundError naming it, and the invocation ends there | The same directory is recorded under failed_directories and the rest of the batch prepares. success reads False only when nothing prepared and at least one directory failed |
| No budget sizing | Resolves each job's width from its own archive at the -w -1 default and stops there, estimating no memory and weighing nothing against a budget. memory_mb, archive_bytes, pool_size, and job_allocations have no CLI counterpart | Sizes every job from its archive's zip directory and admits jobs against resolved core and memory budgets |
Note on -np: The flag reaches only the parallel extraction path. A job that runs sequentially renders no progress
bar whatever the flag says. That covers -w 1, an archive the -w -1 default sizes to a single worker because it sits
below the parallel extraction threshold, and an archive the reader itself batches sequentially because it sits below
the parallel processing threshold. The flag therefore matters mainly for non-interactive runs, where the bar would
otherwise pollute a captured log.
Note on tracker contention: Both paths lock the same microcontroller_processing_tracker.yaml through its .LOCK
file, on the CLI side when the pipeline aligns the tracker and again on every job state transition. A user running axci process against a directory the agent is preparing or executing makes whichever side asks second raise a
TimeoutError. Ask the user to stop their CLI run before preparing or executing that directory, and never start an MCP
batch over a directory the user has a run in.
Fallback: what to tell a user when MCP is unavailable
Only these four MCP capabilities have a CLI path.
| Blocked MCP tool | Tell the user to run |
|---|
list_microcontrollers_tool | axci id -b <baudrate> |
check_mqtt_broker_tool | axci mqtt -h <host> -p <port> |
read_extraction_config_tool | axci config show -c <config> |
prepare_log_processing_batch_tool + execute_log_processing_jobs_tool | axci process -ld <logs> -od <out> -c <config> |
Two caveats on the last row. axci process handles ONE log directory per invocation, so a batch spanning several log
directories becomes one invocation per directory. It also demands a finished extraction configuration. With the server
down, the user generates the precursor with axci config create -m <manifest> -o <config> and fills in the event codes
by hand.
Everything else genuinely blocks until the server is back: manifest read and write, archive assembly, recording
discovery, extraction config write and validate, every batch status, timing, cancel, and reset tool, and every output
verification, query, and cleanup tool. Say so plainly rather than improvising a substitute.
Related skills
| Skill | Relationship |
|---|
/log-processing | Owns the MCP batch workflow and the authoritative lenient sourcing model |
/extraction-configuration | Owns config authoring, validation, and event-code semantics behind axci config |
/microcontroller-setup | Owns manifests, archive assembly, and the discovery behind axci id and axci mqtt |
/communication-mcp-environment-setup | Owns the --help exemption, the hand-launch smoke test, and MCP recovery |
/log-processing-results | Downstream: the feather output both paths write |
/log-input-format | Reference: the assembled archives axci process reads under -ld |
/microcontroller-interface | Context: the PC-side recording code, which no axci command replaces |
/microcontroller:firmware-module | Reference: the serial speed contract behind the axci id baudrate |
/pipeline | Context: where each CLI command sits in the end-to-end pipeline |
Verification checklist
Answering a CLI question:
- [ ] Answered from this skill or from `axci COMMAND --help`, never from memory
- [ ] Quoted the long option form and never presented `-h` as a help alias
- [ ] Named the MCP equivalent alongside any command the agent could have run itself
- [ ] Invoked no `axci` command other than `--help`
Handing a user a CLI command:
- [ ] Confirmed MCP is genuinely unavailable via `/communication-mcp-environment-setup` first
- [ ] Printed the command for the user instead of running it
- [ ] Warned about strict sourcing and the abort-on-first-failure loop before recommending `axci process`
- [ ] Confirmed no MCP batch is holding the tracker for that output directory
- [ ] Told the user to read the standard error stream, because a failed command still exits 0
