Skip to main content

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

python3 -m pip install -e .
pip install nexusquant-cli

nexus-cli

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.

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

nexus-cli admin list reviews [--status all] [--verbose]
nexus-cli admin review strategy <id> --action approve|reject|suspend [--note …]
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

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:

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:

nexusquant strategy list

List signal history for one strategy:

nexusquant strategy signal my_alpha_001 --history --limit 20

Send a single signal:

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:

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

Get non-PII subscriber config for a strategy:

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:

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

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:

{
  "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

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:

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:

{
  "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:

{
  "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 ....

Metadata

Release files for nexusquant-cli 0.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nexusquant-cli 0.6.2
File Size Uploaded Provenance Actions
nexusquant_cli-0.6.2.tar.gz 48.6 kB Without provenance Details for nexusquant_cli-0.6.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nexusquant-cli 0.6.2
File Interpreter ABI Platform Actions
nexusquant_cli-0.6.2-py3-none-any.whl Python 3 none any Details for nexusquant_cli-0.6.2-py3-none-any.whl

Total release size: 108.1 kB

Release files / nexusquant_cli-0.6.2.tar.gz

Download URL nexusquant_cli-0.6.2.tar.gz
Size 48.6 kB
Tags Source
SHA-256 checksum
How to use checksums
dd88f205a0a358b2209d375dc676f07d20531db85c5260d79aa2a49cc22e5b86
BLAKE2b-256 checksum
How to use checksums
159ff00f8b44feba5fef4fbe5941bf87a855d6d867a496f326353759f4a59654
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / nexusquant_cli-0.6.2-py3-none-any.whl

Download URL nexusquant_cli-0.6.2-py3-none-any.whl
Size 59.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d27604f5f388502fe72f0e9a2891a61e82c4f652a1b084606801ea5546dcf528
BLAKE2b-256 checksum
How to use checksums
f9c664a3cbf4436d695bb16bc00f058aafd9b44e6325f82626b663450e45ba1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for nexusquant-cli 0.6.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page