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 thenexus-clisection 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 logoutrevokes 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_USERSflag. Non-admins can only connect once the backend'sNEXUS_AI_BRIDGE_POLICYis 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.