# SigmaVue CLI

Control your [SigmaVue](https://sigmavue.com) trading account from the terminal —
and from any MCP-speaking assistant. `sigmavue` is a thin, read-mostly client
over the public SigmaVue API: check status, journal, and portfolio; manage broker
accounts and copy-trading groups; and place kill-switch-gated simulated trades —
without clicking through the app.

It adds **no** backend logic and bundles **no** trading strategies. Every command
maps to an API endpoint that already ships. Trade execution is fail-closed and
SIM-only.

## Install

Run it without installing (requires [`uv`](https://docs.astral.sh/uv/)):

```bash
uvx --from git+https://github.com/Sigma-Algo/sigmavue-cli sigmavue --help
```

Install from source:

```bash
git clone https://github.com/Sigma-Algo/sigmavue-cli
cd sigmavue-cli
uv sync            # or: pip install -e .
uv run sigmavue --help
```

> `pip install sigmavue` — **coming soon** (PyPI publish pending).

## Quickstart

```bash
# Point at the API (optional). Defaults to the public SigmaVue API.
export SIGMAVUE_API_URL=https://sigmavue-api-green.onrender.com
#   or http://localhost:8000 for a local backend.

sigmavue login --email you@example.com   # password read at a secure prompt
sigmavue status                          # health + account summary
sigmavue accounts list                   # broker accounts your token owns
sigmavue journal list --symbol NQ        # trade journal
sigmavue portfolio                       # open positions + rollup
sigmavue trade execute --symbol NQ --qty 1 --side buy --sim   # SIM-only
sigmavue copy groups list                # copy-trading groups
```

The bearer token is stored at `~/.sigmavue/auth.json` (file mode `0600`).
Passwords are only ever read from a prompt, never accepted as an argument.

## Commands

| Command | What it does |
|---|---|
| `login` / `logout` | Authenticate; store or clear the local token |
| `status` | Backend health + current user + account summary |
| `accounts list` | List broker accounts your token is scoped to (`--active`) |
| `accounts add` | Start a broker OAuth connect (returns an `auth_url` to open) |
| `accounts remove` | Remove a broker account by id |
| `clients list` | List managed trading profiles (enterprise) |
| `journal list` | List trade-journal entries (`--symbol`, `--type`, paging) |
| `portfolio` | Current positions + summary (`--account`, `--status`) |
| `trade execute` | Place an order — kill-switch gated, `--sim` required |
| `copy groups list` | List copy-trading groups |
| `copy groups create` | Create a copy-trading group |
| `copy groups add-follower` | **Coming soon** — use the app for now (see below) |

Exit codes: `0` success · `1` validation / API / trade-refused · `2` not logged in.

## Trading safety

Trade execution is **fail-closed** and re-checked on every call, before any order
request leaves your machine:

1. **CLI live-execution is disabled** — `--sim` is required; SIM routes to your
   active demo broker account.
2. **Local kill-switch** — the CLI refuses to place an order whenever trading is
   turned off, via any of:
   - env `TRADING_ENABLED` set to `0`/`false`/`no`/`off`
   - `~/.sigmavue/killswitch.json` with `{"paused": true}` (a missing or corrupt
     file also blocks — fail-closed)
   - `~/.sigmavue/TRADING_ENABLED` file containing `0`

   Paths are overridable via `SIGMAVUE_KILLSWITCH_PATH` and
   `SIGMAVUE_TRADING_ENABLED_PATH`.
3. **Backend circuit breaker** — the order is refused unless the server-side
   per-user circuit breaker is `CLOSED`.

Rate limits are respected: a stable `User-Agent`/`X-SigmaVue-Client` is sent, and
`429` responses trigger bounded `Retry-After` backoff (`--verbose` surfaces the
rate-limit headers).

## MCP server

The same capability layer is exposed as an [MCP](https://modelcontextprotocol.io)
server, so phone / agent coding assistants get identical reach over one API. It
speaks **stdio** and reads the SAME token `sigmavue login` stores — there is no
credential collection in the MCP surface.

```bash
uv sync --extra mcp        # or: pip install "sigmavue[mcp]"
sigmavue login             # once, in a terminal
uv run sigmavue-mcp        # serves over stdio
```

Add it to an MCP client (use an absolute path so it can start from anywhere):

```json
{
  "mcpServers": {
    "sigmavue": {
      "command": "uv",
      "args": [
        "--directory", "/ABSOLUTE/PATH/TO/sigmavue-cli",
        "run", "sigmavue-mcp"
      ]
    }
  }
}
```

Claude Code:

```bash
claude mcp add sigmavue -- \
  uv --directory /ABSOLUTE/PATH/TO/sigmavue-cli run sigmavue-mcp
```

It exposes eight tools: `sigmavue_status`, `sigmavue_accounts_list`,
`sigmavue_clients_list`, `sigmavue_journal_list`, `sigmavue_portfolio`,
`sigmavue_trade_execute`, `sigmavue_copy_groups_list`, and
`sigmavue_copy_groups_create`. Interactive/destructive flows (login, broker
connect/remove) stay CLI-only.

## Enterprise

Command breadth is decided server-side by your token: a member sees their own
accounts, a manager/enterprise token sees everything it owns — the same
`accounts list` command covers both. A dedicated multi-tenant clients endpoint is
on the roadmap; `clients list` maps to managed trading profiles today.

## Adding copy-trade followers (coming soon)

`copy groups add-follower` is intentionally not enabled from the CLI or MCP yet:
there is no atomic add-follower endpoint, and a client-side read-modify-write of
the follower list would be unsafe. A server-side
`POST /api/v2/trading-groups/{id}/followers` is planned; until then, add
followers in the SigmaVue app. `copy groups list` and `create` work fully.

## Development

```bash
uv sync
uv run pytest -q       # tests use httpx.MockTransport — no live API calls
```

## License

MIT — see [LICENSE](LICENSE) and [NOTICE](NOTICE).