atctl

日本語 README

atctl is a Rust CLI/TUI for sending and managing AT commands for USB cellular modems from macOS on Apple Silicon.

It uses libusb for direct USB access, including cases where macOS does not expose a usable /dev/cu.* serial device.

atctl TUI showing device details, command categories, command list, response output, and saved logs

• Mac: Apple Silicon Mac
• USB modem: SORACOM Onyx LTE USB Dongle
• Internal modem: Quectel EG25-G
• USB ID: 0x2c7c:0x0125
• Observed firmware: EG25GGBR07A08M2G (ATI, 2026年06月17日)

Real-hardware workflows confirmed in this environment:

• USB device discovery and descriptor inspection with devices and inspect, plus direct AT/ATI execution
• Preset execution with masked history and session logging
• TUI candidate refresh and related Sequence input behavior
• PTY bridge operation through screen
• SMS send, receive/list, read, and reply, plus Quectel/SORACOM ping and TCP Sequence workflows

This is the validated environment, not a claim of broad modem or operating system coverage. See the installation guide for the complete validation boundary and runtime prerequisites.

Install atctl with Homebrew:

brew install uchimanajet7/atctl/atctl

The Homebrew formula installs the libusb runtime dependency. See the installation guide for prerequisites and installation checks.

Confirm that the modem is visible and responds to AT commands:

atctl devices
atctl inspect
atctl send AT
atctl send ATI
atctl tui

Use atctl devices to find the current USB target. If the expected modem is not shown, run atctl devices --all-usb and follow the troubleshooting guide.

• Work interactively with atctl tui.
• Send one AT command with atctl send <COMMAND>.
• Find repeatable checks with atctl preset list, inspect one completely with atctl preset show <NAME>, and run it with atctl preset run <NAME>.
• Find multi-step SMS and data-send checks with atctl sequence list, inspect one completely with atctl sequence show <SEQUENCE>, and run it with atctl sequence run <SEQUENCE>.
• Use atctl bridge --symlink <PATH> for a terminal-style PTY bridge.
• Collect raw diagnostic evidence only with an explicit output path and raw-log acknowledgement.

AT commands can read sensitive identifiers and change modem state. atctl masks sensitive output by default and requires confirmation for state-changing or otherwise material actions. Review unfamiliar commands, destination values, and externally supplied preset or Sequence definitions before execution.

Normal send, preset, Sequence, and TUI executions write masked command history and session logs by default:

~/.local/state/atctl/history.jsonl
~/.local/state/atctl/logs/<timestamp>.session.log

--no-log prevents new normal logs only for that invocation; it does not delete existing logs or disable a separately requested raw diagnostic export. Raw diagnostic evidence may contain unmasked sensitive data and is created only when the operator chooses an output path and enters the raw-log acknowledgement.

Read the safety guide before unfamiliar or state-changing operations. See Review and Manage Logs for log locations, review, export, retention, and deletion, and the presets and Sequences reference for definition loading, input assistance, execution review, and workflow details.

• Installation — install, update, remove, and first-run checks
• Presets and Sequences reference — usage, inventory, TOML, and repository examples
• Safety guide — operator precautions and sensitive-data care
• Troubleshooting — diagnosis, recovery, logs, and Response export
• Changelog — notable changes by version

For usage questions, bug reports, and feature requests, search the existing GitHub Issues and open a new issue if needed.

For suspected security vulnerabilities, use GitHub private vulnerability reporting instead of opening a public issue.

For a bug report, include the atctl version when available, the affected command or TUI action, reproduction steps, expected result, actual result, and only reviewed masked output when needed. Do not include raw diagnostic exports, unmasked output, credentials, subscriber identifiers, phone numbers, or message contents in a public issue.

Code and documentation contributions are welcome. Read the contribution guide before opening a pull request.

• Development guide
• Packaging and release guide
• Product and technical specification
• Accepted product and architecture decisions

MIT. See LICENSE.