Metadata-Version: 2.4
Name: talis-cli
Version: 0.2.1
Summary: Command-line client for the Talis trading platform. Sign in via device flow, manage sessions, view portfolio, place orders.
Author: Talis
License-Expression: Apache-2.0
Project-URL: Homepage, https://talis.trade
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Requires-Dist: mcp<2,>=1.0
Requires-Dist: rich>=13
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

# talis-cli

Command-line client for the [Talis](https://talis.trade) trading platform.

```bash
pip install talis-cli

talis login                  # device flow — opens a browser, you approve
talis approve ABCD-EFGH      # approve another login from this signed-in CLI
talis whoami                 # shows current session
talis portfolio              # balance + open positions

talis buy BTC-USD 25         # market buy $25 of BTC
talis close BTC-USD          # close 100% of the BTC position

talis outcome list           # browse live HIP-4 outcome (prediction) markets
talis outcome buy 100 yes 11 # buy $11 of the YES side of outcome 100 (#1000)
talis outcome close 100 yes 25  # sell 25 YES shares of outcome 100

talis sessions               # list active sessions (Connected Devices)
talis sessions revoke ab12   # revoke a session by short prefix
talis logout                 # revoke the current session
```

By default the CLI targets AWS production at `https://api-aws.jarvis.trade`.
Set `TALIS_ENV=render` only when intentionally auditing the legacy Render
deployment, or set `TALIS_API_URL` to override the endpoint completely.

## Read-only sessions

For automation, scripts, or letting an LLM browse your account without
authority to trade, request a `read` scope at login:

```bash
talis login --read-only
```

Read-scope sessions are denied (`403`) on every endpoint that mutates orders,
positions, strategies, or wallets — enforced server-side at the API layer.
When approving a login with `talis approve`, the approving session's scope is
also enforced: a read-only session can only approve read-only CLI access.

## API-key auth (headless / autonomous boxes)

As an alternative to the JWT session, the CLI (and `talis mcp`) can
authenticate with a **per-tenant API key** — no browser, no weekly re-login:

```bash
export TALIS_API_KEY=<per-tenant-key>
export TALIS_TENANT_ID=<tenant-id>       # required: the key carries no claims
talis whoami                             # mode: api-key
```

Or persist both in `~/.talis/config` (JSON, overridable via
`TALIS_CONFIG_PATH`):

```json
{"api_key": "<per-tenant-key>", "tenant_id": "<tenant-id>"}
```

Resolution rules:

- **Key source precedence**: `TALIS_API_KEY` env var > `api_key` in the config
  file. Tenant: `TALIS_TENANT_ID` env var > `tenant_id` in the config file.
- **API key wins over JWT.** When a key is configured, it is used even if a
  `talis login` session (or `JARVIS_TOKEN`) exists — a box with both set
  deterministically uses the key.
- An API key **without** a tenant_id fails with an actionable error at call
  time — set `TALIS_TENANT_ID` or add `tenant_id` to the config file.
- Key scope is server-enforced per request (trade-max; `talis withdraw`
  requires a withdraw-scope JWT session and is not available via API key).
- Session commands (`talis sessions`, self-revoking `talis logout`) are
  JWT concepts: `talis logout` manages the JWT session only and **never
  removes the API key** — remove `api_key` from `~/.talis/config` or unset
  `TALIS_API_KEY` to stop using it.

## Output mode

When stdout is a TTY (interactive shell), commands render with rich formatting.
When stdout is piped or redirected, commands emit one JSON object per line —
suitable for parsing from scripts or LLM agents. Force JSON anywhere with
`--json`.

## Credentials

The CLI stores its session token at `~/.talis/credentials` with `chmod 600`
on POSIX systems. The token is a JWT; treat it like any other credential.

### Sessions renew themselves

You should not have to think about session expiry. When the CLI or the MCP
server runs with under 48 hours left on the clock, it renews in place against
`POST /auth/session/refresh` before doing its work — at most once every 15
minutes, so a burst of commands costs one renewal, not one each. Renewal
preserves the
session's **original grant**, not a fresh maximum — a token issued with a 24h
life renews to another 24h, never to something longer. That is deliberate: an
auto-renewing session must not be able to ratchet itself into a longer-lived
credential than the one you approved.

Renewal is best-effort and silent: if it cannot happen, your existing
credential is left untouched and the command still runs. What you WILL see is a
`session_warning` on MCP tool responses once renewal stops keeping up, or when
under six hours remain. If that appears and keeps counting down, renewal is
failing — run `talis login` to sign in again.

A steady `session_hours_remaining` with no `session_warning` is the healthy
state, not a countdown to worry about.

## Relationship to `cli/jarvis_cli.sh`

The bash script at [`cli/jarvis_cli.sh`](../../cli/jarvis_cli.sh) is the legacy
engineer power tool — admin-keyed, POSIX-only, prose output. It still works
and isn't going anywhere short-term.

**talis-cli is the going-forward client.** All new features (device-flow auth,
per-user credentials, JSON output, scope-aware sessions, future commands)
land here. The bash CLI will be archived once talis-cli reaches feature
parity for admin/engineer workflows.

If you're a Talis engineer with the admin API key, you can keep using either.
If you're a public user or driving the API from an LLM / script, use this one.

## Status

Alpha. APIs may shift. File issues at the
[Talis trading engine repo](https://github.com/Jarvis-Trade/jarvis-trading-engine).


## MCP (Model Context Protocol)

`talis mcp` runs a stdio MCP server that exposes your Talis account as typed
tools — any MCP client (Claude Code, Claude Desktop, other agents) can read
your portfolio, pull Talis Research, place paper trades, create strategies,
set price alerts, and talk to the Talis chat agent. Log in first
(`talis login`); the server authenticates as the logged-in user.

Install and add it to **Claude Code**:

```bash
pip install talis-cli        # or: uv tool install talis-cli
talis login                  # device-flow browser approval, once
claude mcp add talis -- talis mcp
```

No local checkout required — `talis` is on PyPI.

Or to **Claude Desktop** (and other clients using the `mcpServers` config
shape) — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "talis": {
      "command": "talis",
      "args": ["mcp"]
    }
  }
}
```

Tools (25):

`amend_strategy`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
`cancel_order`, `chat`, `close`, `create_strategy`, `history`,
`notifications_create`, `open_orders`, `outcomes`, `packets`, `place_order`,
`portfolio`, `research`, `sell`, `start_strategy`, `stop_strategy`,
`strategies`, `strategy`, `strategy_activity`, `validate_strategy`, `whoami`.

**Safety — read this before pointing an agent at it.** The trading tools
(`buy` / `sell` / `close` / `create_strategy`) execute with **REAL MONEY by
default** (`paper=False`). Pass `paper=True` to simulate instead.

`buy`, `sell` and `create_strategy` additionally refuse to spend real money
unless the caller passes `confirm_real_money=True`. `close` deliberately has no
such gate: a protective exit must never be blocked by a missing flag.
`place_order` (limit orders, spot, HIP-4 outcome markets) has **no paper mode
at all** and refuses without `confirm_real_money=True`.

Set `TALIS_PAPER=1` in the server's environment to force paper mode regardless
of tool arguments.
Withdrawals and wallet creation are not exposed over MCP. For a strictly
read-only agent, log in with `talis login --read-only` — the server rejects
every mutation at the API layer.
