A command-line interface that gives AI agents (Claude Code, Codex, local LLMs, etc.) full access to a local MATLAB R2024b session on macOS — without any human in the loop.
All output is structured JSON so agents can parse results directly.
| Feature | Detail |
|---|---|
| Persistent session | matlab-cli start boots MATLAB once; variables survive across calls |
| One-shot mode | No daemon needed — slower (~6 s) but zero setup |
| Full output capture | fprintf, disp, auto-display — everything goes to output |
| Base workspace | Variables set in one call are available in the next |
| File IPC | Daemon uses ~/.matlab-cli/ request/response files — no port conflicts |
| Structured errors | {"success": false, "error": "..."} on any MATLAB exception |
- macOS with MATLAB R2024b (other versions likely work)
- Python 3.10+
git clone https://github.com/efloresaraya/matlab-cli.git
cd matlab-cli
pip install --editable .Verify:
matlab-cli run "disp(version)"If MATLAB is not at
/Applications/MATLAB_R2024b.app, set:export MATLAB_PATH=/path/to/matlab
# One-shot (no daemon needed)
matlab-cli run "fprintf('%.6f\n', exp(1))"
# Persistent session (variables survive between calls)
matlab-cli start
matlab-cli run "A = magic(4)"
matlab-cli run "fprintf('trace = %d\n', trace(A))" # A still in workspace
matlab-cli get A # returns matrix as JSON
matlab-cli workspace # list all variables
matlab-cli stopmatlab-cli start Start persistent MATLAB session
matlab-cli stop Stop the session
matlab-cli status Show session status (JSON)
matlab-cli run "<code>" Run MATLAB code string
matlab-cli eval "<code>" Alias for run
matlab-cli runfile <path.m> Run a .m script file
matlab-cli get <varName> Get a workspace variable as JSON
matlab-cli workspace List all workspace variables
Global flags:
--pretty Pretty-print JSON output
--timeout N Max seconds to wait (default 120)
Every command prints a single JSON object:
{ "success": true, "output": "result text...", "error": "" }
{ "success": false, "output": "", "error": "Unrecognized variable 'x'." }Exit code 0 = success, 1 = MATLAB error.
matlab-cli start
matlab-cli runfile examples/generate_csv.m # writes examples/sensor_data.csv
matlab-cli runfile examples/read_csv.m # stats + outlier detection
matlab-cli stopgenerate_csv.m simulates 200 temperature/humidity/pressure readings.
read_csv.m reads them back and prints summary statistics per sensor state.
Paste this as system context:
You have access to MATLAB R2024b via `matlab-cli`.
WORKFLOW
matlab-cli start # boot session once
matlab-cli run "<single-line code>" # quick commands
matlab-cli runfile path/to/script.m # multi-line code → write to .m file first
matlab-cli get <var> # retrieve variable as JSON
matlab-cli stop # when done
OUTPUT → {"success": bool, "output": "...", "error": "..."}
RULES
1. Use `start` before multi-step work.
2. Write multi-line code to a .m file, then use `runfile` — never inline newlines.
3. Parse `output` for printed results; use `get <var>` for numeric data.
4. If `success` is false, read `error`, fix the code, retry.
5. Call `stop` when finished.
matlab-cli/
├── matlab_cli/
│ ├── cli.py # argparse entry point
│ ├── batch.py # one-shot mode (matlab -batch)
│ ├── daemon.py # session lifecycle + file IPC
│ ├── client.py # thin wrappers over daemon.send()
│ ├── config.py # paths & constants
│ └── matlab_cli_server.m # MATLAB polling server
├── examples/
│ ├── generate_csv.m # generate sensor data CSV
│ └── read_csv.m # read & analyse CSV
├── pyproject.toml
└── install.sh
MIT