# CLI

The Pier CLI lets you manage agents from your terminal. It's the same interface exposed by the daemon's API, so anything you can do in the app you can do from the command line.

> **Agent orchestration:** You can tell coding agents to use the Pier CLI to spawn and manage other agents. This enables multi-agent workflows where one agent delegates subtasks to others and waits for results.

## Quick reference

```bash
pier run "fix the tests"            # Start an agent
pier ls                             # List running agents
pier attach <id>                    # Stream agent output
pier send <id> "also fix linting"   # Send follow-up task
pier logs <id>                      # View agent timeline
pier stop <id>                      # Stop an agent
```

## Running agents

Use `pier run` to start a new agent with a task:

```bash
pier run "implement user authentication"
pier run --provider codex "refactor the API layer"
pier run --detach "run the full test suite"  # background
pier run --worktree feature-x "implement feature X"
pier run --output-schema schema.json "extract release notes"
pier run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "summarize release notes"
```

The `--worktree` flag creates the agent in an isolated git worktree, useful for parallel feature development.

Use `--output-schema` to return only matching JSON output. You can pass a schema file path or an inline JSON schema object. This mode cannot be used with `--detach`.

By default, `pier run` waits for completion. Use `--detach` to run in the background.

## Listing agents

```bash
pier ls                    # Running agents in current directory
pier ls -a                 # Include completed/stopped agents
pier ls -g                 # All directories
pier ls -a -g --json       # Full list as JSON
```

## Streaming output

Use `pier attach` to stream an agent's output in real-time:

```bash
pier attach abc123   # Attach to agent (Ctrl+C to detach)
```

Agent IDs can be shortened, `abc` works if it's unambiguous.

## Sending messages

Send follow-up tasks to a running or idle agent:

```bash
pier send <id> "now run the tests"
pier send <id> --image screenshot.png "what's wrong here?"
pier send <id> --no-wait "queue this task"
```

## Viewing logs

```bash
pier logs <id>                  # Full timeline
pier logs <id> -f               # Follow (streaming)
pier logs <id> --tail 10        # Last 10 entries
pier logs <id> --filter tools   # Only tool calls
```

## Waiting for agents

Block until an agent finishes its current task:

```bash
pier wait <id>
pier wait <id> --timeout 60   # 60 second timeout
```

Useful in scripts or when one agent needs to wait for another.

## Permissions

Agents may request permission for certain actions. Manage these from the CLI:

```bash
pier permit ls                # List pending requests
pier permit allow <id>        # Allow all pending for agent
pier permit deny <id> --all   # Deny all pending
```

## Agent modes

Change an agent's operational mode (provider-specific):

```bash
pier agent mode <id> --list   # Show available modes
pier agent mode <id> bypass   # Set bypass mode
pier agent mode <id> plan     # Set plan mode
```

## Daemon management

```bash
pier daemon start             # Start the daemon
pier daemon status            # Check status
pier daemon stop              # Stop the daemon
```

Use `PIER_HOME` to run multiple isolated daemon instances.

## Connecting to a remote daemon

`--host` accepts either a local target (`host:port`, a unix socket, or a Windows pipe) or a pairing offer URL, the same `https://app.usepier.sh/#offer=...` link the mobile app uses for QR pairing. With an offer URL the CLI connects through the Pier relay with end-to-end encryption, so you can drive a daemon on another machine without exposing it to the network.

Get an offer URL from the daemon you want to control:

```bash
pier daemon pair --json   # prints { url, qr, ... }
```

Use it from anywhere:

```bash
pier ls --host 'https://app.usepier.sh/#offer=eyJ2IjoyLC...'
pier run --host "$OFFER_URL" "fix the failing tests"
```

You can also set it once via `PIER_HOST` instead of passing `--host` on every command.

## Multi-agent workflows

The CLI is designed to be used by agents themselves. You can instruct an agent to spawn sub-agents for parallel work:

```bash
# Agent A spawns Agent B and waits for it
pier run --detach "implement the API" --name api-agent
pier wait api-agent
pier logs api-agent --tail 5
```

Simple implement + verify loop:

```bash
# Requires jq
while true; do
  pier run --provider codex "make the tests pass" >/dev/null

  verdict=$(pier run --provider claude --output-schema '{"type":"object","properties":{"criteria_met":{"type":"boolean"}},"required":["criteria_met"],"additionalProperties":false}' "ensure tests all pass")
  if echo "$verdict" | jq -e '.criteria_met == true' >/dev/null; then
    echo "criteria met"
    break
  fi
done
```

This pattern enables hierarchical task decomposition, a lead agent can break down work, delegate to specialists, and synthesize results.

## Output formats

Most commands support multiple output formats for scripting:

```bash
pier ls --json                # JSON output
pier ls --format yaml         # YAML output
pier ls -q                    # IDs only (quiet)
```

## Global options

- `--host <target>`, connect to a different daemon (`host:port`, unix socket, or `https://app.usepier.sh/#offer=...` for relay). See [Connecting to a remote daemon](#connecting-to-a-remote-daemon).
- `--json`, JSON output
- `-q, --quiet`, minimal output
- `--no-color`, disable colors