# The command line

pperp puts your accounts in your terminal: sign in once, then read, trade, flatten and follow everything live, or script it with JSON and exit codes.

`pperp` is the Phoenix Perpetuals command line: one small program for macOS, Linux and Windows. It has a command for every API operation, plus short ones for what you do every day.

```bash
pperp positions
pperp buy BTC-USD 0.001 --tp 2% --sl 1%
pperp stream account
```

## Install

```bash title="macOS and Linux"
curl -fsSL https://docs.phoenixperpsfunding.com/install.sh | sh
```

```powershell title="Windows"
irm https://docs.phoenixperpsfunding.com/install.ps1 | iex
```

The installer puts `pperp` in your user folder (no administrator rights), checks the download against the signed checksums of the release, and tells you if it has to add the folder to your `PATH`. `pperp version` shows what you have.

`pperp` is open source (MIT): [github.com/phoenixperps/pperp](https://github.com/phoenixperps/pperp). With Go installed, `go install github.com/phoenixperps/pperp/cmd/pperp@latest` builds it from there instead.

## Sign in

```bash
pperp login --sandbox    # the sandbox
pperp login              # live
```

Your browser opens on the Phoenix Perpetuals sign-in, where you choose what the command line may do: **Read**, or **Read and trade** (on live, trading takes a code we email you), and which accounts. Then you are back in the terminal, signed in for 90 days. Nothing is copied by hand.

- No browser on this computer (a server over SSH)? `pperp login --manual` prints an address to open on any device; you paste back the code it shows.
- The sandbox also takes a sandbox API key: `pperp login --sandbox --api-key` asks for it without showing it, `--api-key-stdin` reads it from a pipe.
- `pperp whoami` says what you are signed in as, its access, accounts and limits. `pperp logout` ends the sign-in on our side too.

The sign-in is kept in your system's keychain (macOS Keychain, Windows Credential Manager, the Secret Service on Linux), never in a file in your home folder. Where there is no keychain, `pperp login --store file` keeps it in a file only you can read.

> [!NOTE]
> On a server, set `PHOENIXPERPS_API_KEY` instead of signing in: pperp uses it for that call and never stores it. It is the only way to use a live API key with pperp.

## Profiles

`live` and `sandbox` are two profiles, each with its own sign-in and settings. `--sandbox` (or `--profile sandbox`) picks one for a command; the first one you sign in to becomes the default.

```bash
pperp profiles                        # which exist, which is the default, which are signed in
pperp profiles use sandbox            # the default from now on
pperp use SANDBOX-00042-001           # the default account of this profile
pperp config set confirm_trades true  # ask before every trade on this profile
pperp login --profile bot --env sandbox   # another profile of your own
```

When a command needs an account, it takes `--account`, else the profile's default account, else your only one.

## Every day

| Command | What it does |
|---|---|
| `pperp accounts` | Your accounts and their state |
| `pperp positions`, `orders`, `fills` | Open positions, working orders (`--status history`), fills |
| `pperp risk` | Equity, margin, and the room left to the daily loss and drawdown limits |
| `pperp history equity`, `history daily` | The equity curve, results by trading day |
| `pperp markets`, `quote BTC-USD` | The markets and their rules, bid, ask and last |
| `pperp buy`, `sell` | A market, limit, stop or stop-limit order, with exits |
| `pperp close BTC-USD` | Close a position (`--percent 50` or `--size`) |
| `pperp cancel ID`, `cancel --all` | Cancel orders |
| `pperp flatten` | Cancel every order and close every position (`--every-account`) |
| `pperp stream account` | Every event of your accounts, live (`--risk` for live risk too) |
| `pperp stream prices BTC-USD ETH-USD` | Prices live; also `book`, `trades`, `candles`, `stats` |

### Orders

```bash
pperp buy BTC-USD 0.01                              # at the market
pperp buy BTC-USD '$500'                            # 500 USD worth at the market, sized down to its step
pperp sell ETH-USD 0.1 --stop <price> --limit <price>  # a stop-limit, below the price for a sell
pperp buy BTC-USD 0.01 --tp 2% --sl 1%              # exits set from the fill price
pperp buy BTC-USD 0.01 --sl 1% --trail 500          # a stop 1% under the fill, trailing by 500
pperp buy BTC-USD 0.01 --leverage 5                 # the market's leverage first
pperp buy BTC-USD 0.01 --dry-run                    # what it would do now; nothing is sent
```

On live, every trade is shown first with what it would do now (the price, the fee, the margin it needs) and placed only when you say yes. Turn it off for a profile with `pperp config set confirm_trades false`. `flatten` and `cancel --all` ask you to type the account's name.

## Every API operation

Every operation of the [API reference](/reference) is a command of the same name: `pperp list-orders`, `pperp set-exits`, `pperp create-strategy`. Path values are arguments, query and body fields are flags, and anything nested goes in `--data` or `--set`:

```bash
pperp list-orders --status history --market BTC-USD --all-pages
pperp get-order ord_01JAB7Q8XK4M2N5P7R9S3T5V7W
pperp set-exits BTC-USD --data @exits.json
pperp place-order --market BTC-USD --side buy --type market --size 0.001 \
  --set exits.stop_loss.percent=1 --set exits.take_profit.0.percent=2
pperp api GET /v1/limits                            # any path, for operations newer than your pperp
```

`pperp help COMMAND` lists a command's flags with what each field means.

## Scripting

On a terminal pperp prints tables; piped, it prints JSON. Choose with `-o table`, `json`, `jsonl` or `csv`, or pick fields with `--jq`:

```bash
pperp positions -o json | jq '.[] | {market, unrealized_pnl}'
pperp fills --all-pages -o csv > fills.csv
pperp risk --jq '.daily_loss.room'
```

Prices and sizes are printed exactly as the API sends them, never rounded.

Writes carry an `Idempotency-Key`. When a call fails without a clear answer (the network dropped), pperp prints its key: check with `pperp orders`, then repeat with `--idempotency-key` and the action happens once at most. Without a terminal to ask, live trades and `flatten` need `--yes`.

### Exit codes

| Code | Meaning |
|---|---|
| 0 | Done |
| 1 | Failed, or you answered no |
| 2 | The command was not used right, or the request was invalid |
| 3 | Not signed in, or not allowed (401, 403) |
| 4 | Not found |
| 5 | Conflict (409) |
| 6 | Refused by a rule of the account or a limit of the key (422) |
| 7 | Rate limited |
| 8 | Our side failed (5xx) |
| 9 | No answer: the network, or an outcome not known |

## When something is off

`pperp doctor` checks your settings, the keychain, the sign-in and its expiry, that the API answers, and your computer's clock. `--verbose` prints every request and answer line, with the credential cut to its last four characters; `--include` prints the rate-limit headers.

## AI assistants on your computer

`pperp mcp` serves the [MCP tools](/mcp) over stdio, signed in as your profile, for assistants that run local servers. It only reads unless you add `--allow-trading`.

```bash
claude mcp add phoenix-perps -- pperp mcp --sandbox
```
