Metadata-Version: 2.4
Name: publicdotcom-cli
Version: 1.3.2
Summary: Command-line client for the Public.com Trading API
Project-URL: Homepage, https://github.com/publicdotcom/publicdotcom-cli
Project-URL: Repository, https://github.com/publicdotcom/publicdotcom-cli
Project-URL: Issues, https://github.com/publicdotcom/publicdotcom-cli/issues
Project-URL: Public.com API, https://public.com/api
Author-email: "Public.com" <developers@public.com>
Maintainer-email: "Public.com" <developers@public.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: api,brokerage,cli,crypto,options,public.com,stocks,trading
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: attrs>=23.2.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.16.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.11.0; extra == 'dev'
Description-Content-Type: text/markdown

# publicdotcom-cli

Command-line client for the Public.com Trading API.

Use `public` to authenticate, inspect accounts, retrieve portfolio and market data, run
preflight checks, and submit order-related requests from your terminal.

## Install

The recommended installation method for command-line Python tools is `pipx`:

```bash
pipx install publicdotcom-cli
```

You can also install with `uv`:

```bash
uv tool install publicdotcom-cli
```

Confirm the CLI is available:

```bash
public --help
```

## Quick Start

Generate a personal secret from your Public.com settings, then authenticate:

```bash
public auth login
public accounts list
public accounts set-default ACCOUNT_ID
public portfolio show
public market quotes AAPL MSFT
```

Most account-scoped commands use the configured default account. You can override it with
`--account-id ACCOUNT_ID` or `PUBLIC_ACCOUNT_ID=ACCOUNT_ID`.

## Important Disclosures

This CLI is a developer tool for interacting with the Public API. It is not investment,
financial, legal, tax, accounting, or trading advice, and it does not recommend any
security, strategy, account type, order type, or transaction.

Trading involves risk, including the possible loss of principal. You are responsible for
reviewing all request payloads, account IDs, symbols, quantities, prices, order sides,
time-in-force values, and other order instructions before submitting a trading command.

Order placement, replacement, and cancellation requests may be asynchronous. A successful
API response confirms submission to the API, not execution, cancellation, fill price,
availability, or final order state. Always verify order status after submitting,
replacing, or cancelling an order.

Market data, quotes, option chains, greeks, account data, and preflight calculations are
provided for informational and operational use through the API. They may be incomplete,
delayed, unavailable, or different from final execution values.

You are responsible for complying with all applicable laws, regulations, exchange rules,
API terms, account agreements, and internal policies that apply to your use of this CLI.
Do not use this tool unless you are authorized to access the relevant account and API
credentials.

Personal secrets and access tokens can authorize account access and trading activity.
Keep them private, do not commit them to source control, and rotate or revoke them if
you believe they were exposed.

## Authenticate

Generate a personal secret from Public, then run:

```bash
public auth login
```

The access token is stored with your OS keychain when available. If no keychain backend
is available, the CLI falls back to a user-only config file.

Access tokens are short-lived. To let the CLI refresh them automatically, opt in to
storing your personal secret:

```bash
public auth login --store-secret
```

Because the personal secret is long-lived, this is optional. The CLI stores it in your
OS keychain when available, otherwise it falls back to a user-only config file.

After that, secured commands automatically mint a fresh access token before the current
token expires or after a `401 Unauthorized` response. You can also refresh manually:

```bash
public auth refresh
```

You can also bypass stored credentials for automation:

```bash
PUBLIC_ACCESS_TOKEN=ey... public accounts list
PUBLIC_PERSONAL_SECRET=... public accounts list
```

Remove stored credentials with:

```bash
public auth logout
public auth logout --all
```

## Default Account

Most API operations require the `accountId` returned by `public accounts list`. You can
store a default account once:

```bash
public accounts set-default ACCOUNT_ID
public accounts get-default
```

Then omit `--account-id` from account-scoped commands:

```bash
public portfolio show
public market quotes AAPL MSFT
public order get ORDER_ID
```

You can override the default at any time:

```bash
public portfolio show --account-id ACCOUNT_ID
PUBLIC_ACCOUNT_ID=ACCOUNT_ID public portfolio show
public accounts clear-default
```

## Example Commands

```bash
public accounts list
public accounts set-default ACCOUNT_ID
public portfolio show
public history list --page-size 25
public instruments get AAPL EQUITY
public instruments bonds --bond-type TREASURY --rating AAA
public market quotes AAPL MSFT --type EQUITY
public market bond-details 912828XG0-BOND
public market option-expirations AAPL
public market option-chain AAPL 2026-05-15
public options greeks "AAPL  260515C00200000"
public options strategy-quote --file examples/strategy-quote.request.json
public historicdata bars EQUITY AAPL YEAR
public historicdata bars EQUITY AAPL DAY --aggregation FIVE_MINUTES
public historicdata bars EQUITY AAPL SINCE_PURCHASE --purchase-date 2024-01-15
public taxlots list
public taxlots symbol AAPL
public taxlots csv --output taxlots.csv
```

## Historic Bar Data

Fetch OHLCV bar data for a symbol over a given time period. The first argument is the instrument type (`EQUITY`, `CRYPTO`, `OPTION`, or `INDEX`):

```bash
public historicdata bars EQUITY AAPL YEAR
public historicdata bars CRYPTO BTC-USD WEEK
```

Available periods: `DAY`, `WEEK`, `MONTH`, `QUARTER`, `HALF_YEAR`, `YEAR`, `FIVE_YEARS`, `YTD`, `SINCE_PURCHASE`.

Override the default bar aggregation with `--aggregation`:

```bash
public historicdata bars EQUITY AAPL DAY --aggregation FIVE_MINUTES
public historicdata bars EQUITY AAPL MONTH --aggregation ONE_HOUR
```

Available aggregations: `ONE_MINUTE`, `FIVE_MINUTES`, `TEN_MINUTES`, `FIFTEEN_MINUTES`, `THIRTY_MINUTES`, `ONE_HOUR`, `ONE_DAY`, `ONE_WEEK`, `ONE_MONTH`, `THREE_MONTHS`, `SIX_MONTHS`, `ONE_YEAR`.

When using the `SINCE_PURCHASE` period, supply the purchase date:

```bash
public historicdata bars EQUITY AAPL SINCE_PURCHASE --purchase-date 2024-01-15
```

Trading requests use JSON files so the exact payload is visible before submission:

```bash
public order preflight-single --file examples/order.single-leg.market-buy.json
public order place --file examples/order.single-leg.market-buy.json
public order replace --file examples/order.replace.notional.json
public order get ORDER_ID
public order cancel ORDER_ID
```

Trading commands prompt before submitting order placement, replacement, or cancellation
requests. Use `--yes` only when your automation has already performed equivalent
validation and approval.

Order payloads accept optional fields beyond the basics shown above. For example,
`useMargin` controls buying power on `order place` and `order place-multileg`: set it to
`false` to evaluate the order against cash-only buying power instead of margin. When
omitted it defaults to `true` (margin applied where the account allows). See
`examples/order.single-leg.cash-only.json` for a sample.

Order-placement and single-leg preflight payloads also accept an optional
`taxLotMatchingInstructions` array (up to 8 entries of `{taxLotId, quantity}`) to specify
which tax lots to close when selling equity. See
`examples/order.single-leg.tax-lot-matching.json` for a sample.

`order replace` submits a cancel-replace request for an open order. The replacement can
specify either a `quantity` or a notional `amount` — the two fields are mutually
exclusive. `--quantity` and `--amount` override the corresponding field in the request
file. Replacement is supported for equity, option, and crypto quantity orders, and is
asynchronous: verify order status after submitting. See
`examples/order.replace.notional.json` for a sample notional replacement payload.

```bash
public order replace --file examples/order.replace.notional.json
public order replace --file examples/order.replace.notional.json --amount 250.00
```

## Tax Lots

Inspect unrealized tax lots for the configured (or `--account-id`) account:

```bash
public taxlots list
public taxlots symbol AAPL
public taxlots symbol AAPL --price 150.00
```

`taxlots symbol` accepts an optional `--price` used to value the lots. Export the full set
as CSV — by default the base64-encoded response is printed, or pass `--output` to decode
and write the CSV file directly:

```bash
public taxlots csv
public taxlots csv --output taxlots.csv
```

## Strategy Quote

Request a quote for a multi-leg options strategy from a JSON request file:

```bash
public options strategy-quote --file examples/strategy-quote.request.json
```

The request body is a `StrategyQuoteRequest` with a `baseSymbol` and an `optionLegs` array
(each leg is `{symbol, side, openCloseIndicator, ratioQuantity}`), plus an optional
`equityLeg`. See `examples/strategy-quote.request.json` for a sample.

## Bonds

Search fixed income instruments with optional filtering, sorting, and pagination:

```bash
public instruments bonds
public instruments bonds --bond-type TREASURY --treasury-subtype NOTE --min-coupon 4
public instruments bonds --rating AAA --rating AA+ --max-maturity-date 2030-12-31
public instruments bonds --page-size 50 --sort-property maturityDate --sort-direction ASC
```

Filters cover issuer, bond status/type, treasury subtype, S&P ratings and outlook,
coupon, maturity dates, current yield, par value, liquidity rating, and
callable/perpetual/partial-par flags. Repeatable options (for example `--rating`) can be
passed multiple times. Results are returned as a page with `content` plus paging
metadata. The API defaults the minimum maturity date to today + 14 days to exclude bonds
nearing maturity with volatile yields; pass `--min-maturity-date` to override.

Retrieve comprehensive details for a single bond — pricing, ratings, coupon, and
maturity/call information — using the configured (or `--account-id`) account. The bond
symbol is typically in `CUSIP-BOND` format:

```bash
public market bond-details 912828XG0-BOND
```

## JSON Output

Use `--json` before the command group to print raw JSON:

```bash
public --json accounts list
public --json market quotes AAPL MSFT
```

## Configuration

The CLI supports these environment variables:

```bash
PUBLIC_ACCESS_TOKEN=...
PUBLIC_PERSONAL_SECRET=...
PUBLIC_ACCOUNT_ID=...
PUBLIC_API_BASE_URL=https://api.public.com
PUBLIC_AUTO_REFRESH=true
```

`PUBLIC_API_BASE_URL` is optional and defaults to `https://api.public.com`.

## Upgrade

```bash
pipx upgrade publicdotcom-cli
# or
uv tool upgrade publicdotcom-cli
```

## Development

For local development from a checkout:

```bash
uv sync --extra dev
uv run public --help
uv run pytest
```

## Regenerate The OpenAPI Client

The package ships with a generated API client. Contributors who need to regenerate it
must place the local OpenAPI spec at the repository root as `spec.yaml`, then run:

```bash
uv run python scripts/generate_client.py
```

The raw spec uses `*/*` for many JSON responses, which some Python generators do not
parse as JSON. The regeneration script normalizes those response content types before
running `openapi-python-client`. This requires network access the first time because it
uses `uvx openapi-python-client`.
