Metadata-Version: 2.5
Name: nexusquant-cli
Version: 0.5.0
Summary: NexusQuant CLI for users, strategy providers and admins
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: nexusquant-sdk>=0.2
Requires-Dist: platformdirs>=4.2
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# nexusquant-cli

Command line tool for NexusQuant investors, strategy providers and admins.

It supports browser login through Cognito, stores tokens locally, refreshes tokens, and calls the Nexus APIs. Two entry points share one login:

- **`nexus-cli`** — role-first grammar, `nexus-cli <role> <verb> <resource> [args]`. Use this.
- `nexusquant` — the original flat provider layout (`nexusquant strategy|policy …`), kept unchanged for existing scripts. Everything below the `nexus-cli` section documents it.

## Install

```bash
python3 -m pip install -e .
```

```bash
pip install nexusquant-cli
```

## nexus-cli

```bash
nexus-cli auth login          # browser login; one login covers every role
nexus-cli auth whoami         # account, userType, Wall Pro tier, usable roles
nexus-cli auth login --device # no local browser (server, SSH): approve a link + code from any browser
```

`--device` gives you a **Nexus AI token** instead of a Cognito login:
- It works for investor commands only; provider and admin commands are refused by the server.
- It is valid for 90 days and can be revoked at any time.
- `auth logout` revokes it on the server.
- The same token kind is what the Nexus AI Discord bot uses.

The role is not picked at login — it is the account's `custom:userType` (or the `admin` Cognito group), and the server checks it on every call. `whoami` reads it from the local token; on a 403 the CLI prints which account type is logged in.

Every read takes `--json` for scripting; the default output is a table.

### investor — any logged-in account

| Command | What it does |
|---|---|
| `investor list strategies [--subscribed]` | Marketplace, with backtest summary and a flag for strategies whose sizing reads your holdings |
| `investor read strategy <id>` | Detail + 30 most recent signals |
| `investor read backtest <id>` | Backtest stats, rolling returns, per-ticker attribution, return since you added it |
| `investor subscribe strategy <id>...` | Add to My Strategies (Wall Pro). **Does not start auto-trading** |
| `investor unsubscribe strategy <id> [-y]` | Remove from My Strategies; asks first, and warns if it is listening (this stops auto-trading) |
| `investor list subscriptions` | My Strategies: listening on/off, config saved, broker |
| `investor read config <id>` | Your personal config, effective config, and the schema of what you can set |
| `investor list signals [--strategy-id --status --direction --limit --offset]` | Signals that reached you, with your own broker result for each |
| `investor read stats` | Signal counts and broker success rate |
| `investor read profile` / `investor read settings` | Account; daily-report setting |
| `investor update settings --daily-report/--no-daily-report` | Toggle the daily report email |
| `investor read container` | Trading environment state, broker login, selected account |
| `investor list brokers` | Supported brokers and their login fields |
| `investor list activity` | Your own activity log |

#### Nexus AI agent — permissions and logs

Nexus AI is the agent you chat with in the web app. Commands for the agent are under `investor`, and you can only **narrow** what it may do. The ceiling comes from your profile and is enforced on the agent host.

```bash
nexus-cli investor read agent-access                       # enabled?, profile, tools, extra denied tools
nexus-cli investor update agent-access --profile readonly  # investor | readonly (admins: operator) | default
nexus-cli investor update agent-access --deny-tool Write --deny-tool Edit
nexus-cli investor update agent-access --clear-deny
nexus-cli investor list agent-sessions                     # past conversations: title, turns, tool calls, denials, cost
nexus-cli investor read agent-session ws-…                  # the full conversation, as it happened
nexus-cli investor delete agent-session ws-…                # remove it from your history (soft delete)
nexus-cli investor list agent-logs --denied                # every refused tool call
nexus-cli investor list agent-logs --session ws-… --event tool_executed
```

| Profile | Tools | Files |
|---|---|---|
| `investor` | Read, Glob, Grep, Write, Edit, MultiEdit, TodoWrite, WebSearch. No shell, no sub-agents, no WebFetch | Only your own workspace |
| `readonly` | `investor` without the write tools | Only your own workspace |
| `operator` (admins only) | Everything | The whole agent workspace |

- Conversations are kept permanently so you can read your history. Deleting one hides it from you; the platform keeps a copy, and admins can still see it.
- Audit entries (the per-tool-call log) are kept for 90 days.
- Changes apply to sessions opened afterwards.
- Every tool call is logged: which tool, a summary of its input, and whether it was auto-allowed, approved by you, or refused. Refusals record who refused it: the profile, you, or a timeout.
- Each turn also logs its cost.

Not in the CLI yet, on purpose: switching listening on (arms auto-trading), editing sizing config, broker connect, container start/stop/reset, and webhook strategies. They place real orders or carry broker secrets and need their own confirmation / secret-handling design — see `docs/investor-operations.md`.

### provider — `custom:userType=strategyProvider` or admin

| Command | Same as legacy |
|---|---|
| `provider create strategy -i ID -n NAME [--schema-file …]` | `nexusquant strategy create` |
| `provider list strategies` | `nexusquant strategy list` |
| `provider list signals <id> [--limit --offset --status --direction]` | `nexusquant strategy signal <id> --history` |
| `provider send signal <id> --ticker … --direction … --price … --quantity …` / `--signals-file` | `nexusquant strategy signal <id> --ticker …` |
| `provider list subscribers <id>` | `nexusquant strategy sub config <id>` |
| `provider list features [--scope --json]` | `nexusquant policy features` |
| `provider publish policy --strategy-id … --ticker … --file …` | `nexusquant policy publish` |
| `provider list policies <id>` | `nexusquant policy list` |
| `provider update policy --policy-id … --mode off` | `nexusquant policy set-mode` |
| `provider send policy-signal …` | `nexusquant policy send-signal` |

Options are identical to the legacy commands documented below. One difference: `provider send signal` with no send fields is an error, where the legacy `strategy signal` silently listed history.

### admin — `custom:userType=admin`

```bash
nexus-cli admin list reviews [--status all] [--verbose]
nexus-cli admin review strategy <id> --action approve|reject|suspend [--note …]
```

```bash
nexus-cli admin list agent-access                       # who besides admins may use Nexus AI
nexus-cli admin grant agent-access --email someone@x.com
nexus-cli admin revoke agent-access --email someone@x.com
nexus-cli admin list agent-sessions [--email … | --user-id …] [--include-deleted]
nexus-cli admin read agent-session ws-…                  # any user's conversation; each read goes into your admin activity log
nexus-cli admin list agent-logs --email someone@x.com --denied
```

How grant and revoke take effect:
- Granting adds the user to the `NEXUS_AI_USERS` flag. Non-admins can only connect once the backend's `NEXUS_AI_BRIDGE_POLICY` is also on.
- Revoking refuses new connections within about 30 seconds. A session that is already open closes at its next token renewal; the web app renews every 20 minutes.

Agent ops (weekly analysis uploads, S3 reads, Discord KB, notify) stay in `nexus-agent` (nexus-agent-cli) for now.

## Legacy `nexusquant` commands

### Login

```bash
nexusquant auth
nexusquant auth --status
nexusquant auth --refresh
nexusquant auth --logout
```

Tokens are stored in the current OS user's config directory, for example `~/Library/Application Support/nexusquant-cli/credentials.json` on macOS. The file is written with `0600` permissions when supported.

## Strategy Commands

Create or update a strategy:

```bash
nexusquant strategy create \
  --strategy-id my_alpha_001 \
  --name "My Alpha" \
  --schema-file schema.json \
  --output-unit SHARE_COUNT
```

List strategies registered by the current provider. Admin users see all strategies:

```bash
nexusquant strategy list
```

List signal history for one strategy:

```bash
nexusquant strategy signal my_alpha_001 --history --limit 20
```

Send a single signal:

```bash
nexusquant strategy signal my_alpha_001 \
  --strategy-name "My Alpha" \
  --ticker AAPL \
  --direction buy \
  --price 150.25 \
  --quantity 100 \
  --order-type MARKET
```

`--order-type` is a signal-level setting: `MARKET` or `LIMIT` (limit uses `--price`). Legacy `NORMAL` is accepted by the CLI as an alias for `LIMIT`. If omitted, the API defaults to `MARKET`.

Send a multi-route `signals` map:

```bash
nexusquant strategy signal my_alpha_001 \
  --strategy-name "My Alpha" \
  --signals-file signals.json
```

Get non-PII subscriber config for a strategy:

```bash
nexusquant strategy sub config my_alpha_001
```

## Policy Commands

A SizingPolicy replaces the fixed `--quantity` on a signal with a **formula** that
decides the order quantity — and optionally a limit price — at order time. You
publish the formula once; each signal then carries only the parameter values it
needs. Values that depend on the individual subscriber's account are never sent by
you: they are bound inside that user's own container when the order is placed.

Requires `custom:userType=strategyProvider` or `admin`, the same as the strategy
commands.

### See which names a formula may use

The server registry is the authority — a name outside it cannot be published. Run
this before writing a formula:

```bash
nexusquant policy features
nexusquant policy features --scope shared    # names you send with each signal
nexusquant policy features --scope account   # names bound in the user's container
nexusquant policy features --json            # raw output for scripting
```

Account-scoped names carry a "suppliable" flag: a name that exists but that the
container cannot currently supply will pass your editor and fail at publish.

### Publish a formula

```bash
nexusquant policy publish --strategy-id my_alpha --ticker TQQQ --file tqqq.json
nexusquant policy publish --strategy-id my_alpha --ticker TQQQ --file tqqq.json --profile normal
```

`--file` holds the two things a policy is made of — the formulas keyed by output
slot, and the names you promise to supply with every signal:

```json
{
  "expr": {
    "f_depth":       "exp(-k_depth * depth / 10)",
    "buy.quantity":  "target_shares * f_depth * clamp(1 - pos_ratio, 0, 1)",
    "buy.price":     "ref_price * (1 - slip)",
    "sell.quantity": "held_shares * exit_frac"
  },
  "params": ["target_shares", "k_depth", "depth", "ref_price", "slip", "exit_frac"]
}
```

Output slots — the container picks the one matching the signal's direction:

| Slot | What the formula yields |
|---|---|
| `buy.quantity` / `sell.quantity` | **Share count** (floored) |
| `buy.price` / `sell.price` | **Limit price** — supplied ⇒ limit order, omitted ⇒ market order |

Intermediate names (`f_depth`) are fine, but an `expr` must define at least one
output slot, and an intermediate name may not contain a dot. `--ticker` is separate
from the file because it is not part of the artifact: the same formula pointed at
another symbol is the same formula.

⚠️ **`publish` IS the go-live action.** There is no shadow or canary step, and the
previous version on the same slot is deactivated. `--profile` defaults to `normal`.

Before sending anything, the CLI fetches the registry and checks locally that every
free name in your formula has someone to supply it — forgetting to list a name in
`params` is the most common mistake. `--skip-name-check` disables that fetch, and
then local success does not imply the server will accept.

### List and stop

```bash
nexusquant policy list my_alpha
nexusquant policy list my_alpha --ticker TQQQ --mode active   # --mode active / off

# Emergency stop for a live version — not a promotion step, since publish already went live
nexusquant policy set-mode --policy-id 'TQQQ/normal/…/abc123' --mode off
nexusquant policy set-mode --policy-id 'TQQQ/normal/…/abc123' --mode active
```

### Send a signal against a policy

Every declared parameter must be present, or the signal is rejected:

```bash
nexusquant policy send-signal \
  --strategy-id my_alpha --ticker TQQQ --price 51.2 --direction buy \
  -p target_shares=10 -p k_depth=0.5 -p depth=3 \
  -p ref_price=51.2 -p slip=0.002 -p exit_frac=0.25

# Or pass all parameter values as a JSON object
nexusquant policy send-signal --strategy-id my_alpha --ticker TQQQ \
  --price 51.2 --direction buy --params-file params.json

# Validate and print the payload without sending it
nexusquant policy send-signal ... --dry-run
```

| Flag | Meaning |
|---|---|
| `--param` / `-p` | One parameter value, `name=value`; repeat per declared name |
| `--params-file` | A JSON object with all parameter values instead |
| `--policy-id` | Defaults to the active policy on this `(strategy, ticker)` |
| `--quantity` | Used when the formula has no slot for this direction |
| `--order-type` | `MARKET` / `LIMIT` |
| `--strategy-name` | Defaults to the strategy id |
| `--no-fetch` | Skip fetching the policy — see below |
| `--dry-run` | Validate and print the payload, send nothing |

By default the CLI fetches the active policy first and uses it to validate and
coerce your values. Three checks, each mirroring the server:

| Situation | Result | Why not something else |
|---|---|---|
| A declared parameter is missing | Error | No defaults — a default turns "unknown" into "known" |
| A name you did not declare | Error | The formula cannot reference it; extra names mean the two sides disagree |
| An account-state name (`pos_ratio`, `held_shares`, …) | Error | Its value never leaves the execution plane |

`--no-fetch` skips the fetch, and then **only the account-state rule is checked** —
the rest is unknowable locally, so it is not pretended.

⚠️ **The server is always the authority.** Passing local validation does not mean
the server will accept — policy state and review status live there. This layer only
moves the obvious mistakes onto your machine, where you can see which field is
wrong instead of guessing from a rejection.

⚠️ **There is no publish-time bound on order size.** Parameters are names only,
with no declared domain, so nothing proves at publish time that a formula stays
under a limit. How large an order it can place is clamped at order time by the
subscriber's own `max_order_cash_usd`. Keep your formulas in a sane range yourself.

## JSON Inputs

`--schema-file` must contain the `strategy_schema` object accepted by `nexus-service`, for example:

```json
{
  "type": "object",
  "properties": {
    "window": {
      "type": "integer",
      "default": 14,
      "title": "Window",
      "source": "user"
    }
  },
  "required": []
}
```

`--signals-file` must contain a JSON object whose keys are `default` or user ids:

```json
{
  "default": {
    "ticker": "AAPL",
    "time": "2026-04-26T19:30:00Z",
    "price": 150.25,
    "direction": "buy",
    "order_type": "LIMIT",
    "quantity": 100,
    "metadata": {}
  }
}
```

## Environment Overrides

Normal use does not require configuration. For staging or local development:

| Variable                       | Meaning                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------- |
| `NEXUSQUANT_API_ENDPOINT`      | API endpoint host, default `https://api.nexusquant.co`; CLI calls `/api/...` under it |
| `NEXUSQUANT_API_BASE_URL`      | Optional full API base override, e.g. `https://api.nexusquant.co/api`                 |
| `NEXUSQUANT_COGNITO_DOMAIN`    | Cognito Hosted UI host, default `auth.lookatwallstreet.com`                           |
| `NEXUSQUANT_COGNITO_CLIENT_ID` | Cognito app client id                                                                 |
| `NEXUSQUANT_REDIRECT_URI`      | OAuth callback, default `http://127.0.0.1:8251/callback`                              |

There is also a hidden typo-compatible alias: `nexusquant startegy ...` maps to `nexusquant strategy ...`.
