Metadata-Version: 2.5
Name: mindvest-atlas
Version: 0.95.1
Summary: Atlas CLI — OAuth login, tool calls, and live alert/flow streaming for the Atlas trading API
Project-URL: Homepage, https://github.com/finmanagerai/atlas-cli
Project-URL: Repository, https://github.com/finmanagerai/atlas-cli
Project-URL: Issues, https://github.com/finmanagerai/atlas-cli/issues
Author: FinManagerAI
License: MIT
License-File: LICENSE
Keywords: atlas,cli,mcp,mindvest,oauth,options,trading
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Provides-Extra: watch
Requires-Dist: mss>=9; extra == 'watch'
Requires-Dist: pillow>=10; extra == 'watch'
Description-Content-Type: text/markdown

# Atlas CLI (Python)

The Python implementation of the Atlas CLI. Zero third-party dependencies — pure
standard library, Python ≥ 3.8.

## Install

```sh
pipx install mindvest-atlas      # recommended (isolated)
# or
pip install --user mindvest-atlas
atlas login
```

Or run from a clone without installing:

```sh
cd python
python -m atlas_cli --help
```

## Usage

See the [top-level README](../README.md) for the full command reference. Quick
tour:

```sh
atlas login
atlas tools
atlas stock-quote --symbol SPY
atlas options-chain --symbol SPY --expiration 2026-06-20
atlas historical-contract --symbol NVDA --expiry 2026-07-13 --strike 205 --side call --from 2026-07-06 --to 2026-07-10
atlas alerts --symbol SPY --name greek_exposure --save-charts ./charts
atlas flow stream --symbol NVDA
```

## Layout

```
atlas_cli/
  cli.py              # arg parsing + command dispatch + entry point (`run`)
  config.py           # constants, endpoints, paths
  pkce.py oauth.py loopback.py store.py   # auth: PKCE, OAuth, callback server, 0600 store
  client.py catalog.py stream.py _http.py # API client (+ auto-refresh), catalog, SSE
  ui.py args.py help.py format.py stream_loop.py
  commands/           # login, logout, whoami, tools, call, alerts, flow
tests/                # unittest suites (offline)
```

## Test

```sh
python -m unittest discover -s tests
```

Runs PKCE/arg/SSE/storage unit tests plus integration tests that drive the real
OAuth client and loopback server against in-process mock servers — no network
required.

### Plays (signals) — `atlas signals <command>`

```
atlas signals groups                              # groups you post to, and the ones you follow
atlas signals plays --board community --days 1    # the plays themselves
atlas signals performance --group <id> [--mine]   # closed trades + win rate, like a workflow's
atlas signals delete --group <id>                 # refuses while people are subscribed, and says how many
atlas signals delete --group <id> --stop-subscribers   # stops their billing, tells them, then deletes
atlas signals take --id <play> --contracts 1      # place a play in YOUR account
atlas signals post --symbol SPY --call --strike 765 --expiry 2026-09-14 \
  --entry 765 --target 765.5 --stop 764 --group <id>      # post a play
atlas signals post --symbol SPY --call --strike 765 --expiry 2026-09-14 --entry 765 \
  --link oco --with-put --with-strike 760 --with-entry 759   # a LINKED pair: one cancels the other
atlas signals <show|discover|follow|schema>
```

### Alerts — list and clear them out

```
atlas alerts list [--all] [--symbol SPY]          # your alerts WITH their ids ( --all includes the off ones)
atlas alerts delete --id <id> --id <id2>          # switch them off and hide them
atlas alerts delete --id <id> --purge             # delete the rows for good
```

`--purge` refuses any alert a live workflow is still bound to and names
what holds it: that binding is only an id, so removing the row would leave the
setup pointing at nothing and quietly never firing.

`atlas alerts` on its own is still the live feed.

### Tell your phone

```
atlas phone-notify --title "Backtest done" --body "SPY: 61% win, 214 trades" --key backtest
atlas phone-notify --title "Backtest running" --key backtest --progress 0.4     # a bar; the same key edits it
atlas phone-notify --title "Backtest done" --key backtest --button "Run on QQQ" --project spy-backtest
```

A notification on your own phone (the MindVest Atlas app), from the command
line, a script or a model. The layout is fixed and you fill it in: a title (cut
at 40 characters), two short lines, a bar, one button. The same `--key` replaces
what is showing instead of adding to it. The button starts `--project` on your
computer (Local Mode) with the press in `$ATLAS_JOB_PAYLOAD` under `phone`; a
script that is still running asks `atlas phone-button --key <key>` instead. In a
project's own script it is `notify(...)` and `phone_press()` from `atlas_env`.
At most 30 new ones an hour; switch them off in Profile, Manage notifications,
Studio.

### Trade settings, paused workflows, sharing, the marketplace

Everything below was only on the website before 0.93.1.

```bash
atlas signal-trade-settings                                   # your defaults, accounts, and every group's settings
atlas signal-trade-settings --max-per-trade 230               # your budget for one trade
atlas signal-trade-settings --group-id <id> --accept-mode auto --max-per-trade 150
atlas signal-take --signal-id <id> --late true --max-per-trade 230
atlas signal-my-order --signal-id <id> --contracts 2          # or --cancel true
atlas signal-pending                                          # plays waiting for your yes or no
atlas signal-answer --signal-id <id> --accept true

atlas workflow-restore --workflow-id <id>                     # turn a paused workflow back on
atlas workflow-review --workflow-id <id>                      # the run held for review; then --action place|discard --review-id <id>
atlas workflow-abort --workflow-id <id>                       # stop a run in progress
atlas workflow-follow --workflow-id <id> --follow false       # make an imported copy your own
atlas workflow-history --workflow-id <id>                     # earlier versions; --version-id <id> --restore true goes back

atlas workflow-collab-find --query ada
atlas workflow-collab-set --workflow-id <id> --user-id <id> --roles '["writer","operator"]'
atlas marketplace-mine                                        # what you sell and what you pay for
atlas marketplace-listing-update --kind signal_group --ref-id <id> --price 20 --status live
```

### Every tool, as a command

[docs/TOOLS.md](docs/TOOLS.md) lists all of them, generated from the live
registry. Anything the server registers is callable as `atlas <slug> --flag
value` the moment it exists — the catalog is fetched, not shipped
(`atlas tools --refresh` re-reads it).
