---
title: pony CLI
description: Use the bundled pony command to list, inspect, read, and send input to active PonyMux Terminals from scripts or another authenticated Terminal.
sidebar:
  badge: Experimental
---

The experimental `pony` CLI is available in every regular PonyMux Terminal through
`PATH`. It is a
local control surface for inspecting and coordinating active Terminals without adding
a project, task, or orchestration model to the app.


*PonyMux interface view: cli.*


## Commands

```sh
pony list
pony inspect <terminal-id>
pony read <terminal-id> --lines 80
pony send <terminal-id> "Continue with the review"
```

### `pony list`

Lists active Terminals with their id, title, working directory, live state, and agent
status. Archived and trashed Terminals are not included.

Use an id from this output with the other commands.

### `pony inspect`

Returns the selected Terminal's summary and the current Inspector session facts, such
as provider, model, effort, context size, and last request time when available.

### `pony read`

Reads text from a live Terminal screen. It returns 80 lines by default; `--lines` accepts
values from 1 through 2,000.

```sh
pony read <terminal-id> --lines 200
```

### `pony send`

Clears the target's current input line, pastes the supplied text, and presses Enter.
The target must have a live PTY that can receive input.

If no text argument is provided, `pony send` reads from standard input:

```sh
printf '%s' "Run the focused tests" | pony send <terminal-id>
```

Use `--` before text that begins with an option-like prefix:

```sh
pony send <terminal-id> -- "--help"
```

Send input is limited to 64 KiB per request and 60 requests per minute.

## JSON output

All four commands support `--json` for scripts and agents:

```sh
pony list --json
pony inspect <terminal-id> --json
pony read <terminal-id> --lines 120 --json
pony send <terminal-id> --json "Continue"
```

## Security boundary

`pony` is not a network API. PonyMux accepts a request only when macOS process facts
authenticate it to a live source Terminal and the current Terminal generation. Requests
from an unrelated process or a stale Terminal are rejected.

The command addresses the PonyMux app bundle that supplied its executable. Development
variants therefore control their own Terminals by default. Cross-app control works only
when both app bundles belong to the same verified local signing domain.