PierPier
View as markdown

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

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:

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

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:

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:

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

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:

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:

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):

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

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:

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

Use it from anywhere:

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:

# 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:

# 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:

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.
  • --json, JSON output
  • -q, --quiet, minimal output
  • --no-color, disable colors