Metadata-Version: 2.4
Name: actorio-cli
Version: 0.1.2
Summary: CLI and MCP server for searching the Actorio product catalogue
Author-email: Actorio <dev@actorio.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/actorio-com/actorio-cli-mcp
Project-URL: Documentation, https://github.com/actorio-com/actorio-cli-mcp#readme
Keywords: actorio,ecommerce,amazon,cli,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.0
Requires-Dist: starlette>=0.37
Requires-Dist: uvicorn>=0.30
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.24; extra == "test"
Requires-Dist: respx>=0.21; extra == "test"
Dynamic: license-file

# actorio-cli

A command-line client and MCP server for Actorio's product search. It wraps the
same search endpoints the web UI uses (products, favorites, Amazon, reverse
lookup) and exposes them both as interactive CLI commands and as tools for AI
assistants via the Model Context Protocol.

## Install

Install from PyPI — pipx is recommended so the `actorio` entry point gets an
isolated environment:

```bash
pipx install actorio-cli
# or, if you prefer a plain pip install into your environment:
pip install actorio-cli
```

For development against a local checkout:

```bash
pip install -e ".[test]"
```

Both methods install the `actorio` entry point on your `PATH`.

## Updates

The CLI checks PyPI for a newer release once a day (in the background, so it
never slows a command down) and prints an upgrade notice to stderr:

```
A new version of actorio-cli is available: 0.2.0 (installed: 0.1.0).
Run `pipx upgrade actorio-cli` to update.
```

The notice never touches stdout, so `--json` pipelines stay clean, and it is
disabled while running `actorio mcp`. Skip the check entirely with
`ACTORIO_NO_VERSION_CHECK=1` (useful in CI). `actorio --version` shows the
installed version.

## Authentication

> **Note:** `clitest.actorio.com` is a temporary test instance — the base URL
> will move to the production API (`api.actorio.com`) in the future.

Log in once per machine using the device-code flow:

```bash
actorio login --base-url https://clitest.actorio.com
```
```

The CLI prints a short user code and a verification URL. Open the URL in a
browser where you are already signed in to Actorio and approve the request.
The CLI polls until the approval lands, then writes a token to
`~/.actorio/config.json` with file mode `0600`.

To revoke a token, use the Actorio account settings page (coming soon — for
now, contact Actorio support or run `actorio logout` locally to forget the
token on this machine).

## Commands

Every search command accepts `--limit` (server default 20, or 16 for reverse search; max 100), `--offset` (default 0) and `--json`.
Without `--json`, results render as a Rich table mirroring the webapp
product table: identifiers (ASIN/EAN/SKU), Amazon + supplier titles,
VAT-aware supplier price (net/gross with EUR equivalents), and
per-marketplace rows (DE/ES/FR/GB/IT) for Amazon price, sellers (with FBA
count), unit profit, unit ROI, monthly sales and monthly profit, plus the
monthly totals. With `--price-reference avg30` the table switches to the
30-day-average price/profit columns, like the webapp toggle. `--json`
returns every field the backend has for each row.

- `actorio login --base-url URL [--label LABEL]` — start the device-code
  login flow and store the issued token.
  ```bash
  actorio login --base-url https://clitest.actorio.com --label laptop
  ```
- `actorio logout` — delete the local config file.
  ```bash
  actorio logout
  ```
- `actorio whoami` — print the stored base URL, token label, and username.
  ```bash
  actorio whoami
  ```
- `actorio products search [QUERY] [filters...] [--limit 20] [--offset 0] [--json]`
  — search the product catalog with the full webapp filter set.
  ```bash
  actorio products search "lego star wars" --country DE --price-max 50
  actorio products search --roi-min 30 --profit-month-min 200 --marketplace DE --missing-fba
  ```
- `actorio favorites search [QUERY] [filters...] [--limit] [--offset] [--json]`
  — search your saved favorites (same filters as products).
  ```bash
  actorio favorites search headphones --json
  ```
- `actorio amazon search [QUERY] [filters...] [--limit] [--offset] [--json]`
  — Amazon Flip: cross-marketplace Amazon-to-Amazon arbitrage. `--store` is
  the source marketplace you buy from; `--marketplace` the target you compare
  against.
  ```bash
  actorio amazon search --store amazon.es --marketplace DE --roi-min 20
  ```
- `actorio reverse search ASINS [--actorio-only] [--limit] [--offset] [--json]`
  — reverse lookup for one or more ASINs (comma or space separated).
  ```bash
  actorio reverse search "B09XYZ1234,B08ABC5678"
  ```
- `actorio products|favorites|amazon|reverse export [filters...] [--format csv|xlsx] [--output FILE]`
  — download the full filtered result set (up to 2500 rows), matching the
  web UI's export buttons. Exports cost more credits than searches.
  ```bash
  actorio amazon export --marketplace DE --roi-min 20 --format xlsx -o flips.xlsx
  ```
- `actorio usage` — show your credit balance, allowance and reset date.
- `actorio buy-credits [--no-open]` — open the credit-pack purchase page
  (billing happens in the Actorio web app).
- `actorio mcp` — start the MCP server on stdio. Intended to be launched by
  an MCP-capable client, not run interactively.

### Advanced filters

Every filter the web UI offers is available as a flag on
`products`/`favorites` (and most on `amazon`) search/export commands:

`--country`, `--type` (RTL/WHL/UPL/EXC), `--store` (repeatable),
`--upc-list`, `--asin-list`, `--price-min/max` (supplier price VAT
incl., i.e. the web UI's "Supplier Price" filter), `--marketplace`
(DE/ES/FR/GB/IT), `--price-reference avg30`, `--last-update 24|48`,
`--missing-fba` (keep only complete-FBA listings), `--exclude-multipack`,
`--exclude-variations`, `--exclude-hazmat`, `--exclude-suppressed-buybox`,
`--size` (repeatable), `--category` (repeatable),
`--similarity 0-3`, `--competitive-price-min/max`, `--profit-min/max`,
`--roi-min/max`, `--profit-month-min/max`, `--sales-month-min/max`
(each range has a `--*-logic all` variant: blank = ANY marketplace,
`all` = ALL marketplaces), and `--sort` (e.g. `profit`, `-profit`,
`identifiers`, `price`, `last_scan`, `last_update`).

Plan limits apply exactly as on the web: e.g. filters your plan doesn't
include are ignored/forced server-side, and product exports require the
full-search permission.

## Output formats

By default, results print as a human-friendly Rich table. Pass `--json` for
machine-readable output — this is the format MCP tools and any scripting use.
JSON output includes both `results` and `pagination` (with `total`, `page`,
`per_page`, and `has_more`).

## MCP setup for Claude Desktop

Add an entry to your Claude Desktop `mcp.json`:

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

The MCP server exposes these tools, each mirroring the parameters of the
matching CLI command (including all advanced filters):

- `search_products`
- `search_favorites`
- `search_amazon` — Amazon Flip arbitrage search
- `reverse_lookup` — takes `asins` (comma/space separated)
- `export_results` — saves a CSV/XLSX export to a local path
- `get_usage` — credit balance and reset date

Search responses include `_meta.credits` (cost, remaining, reset) so agents
can track spend. You must `actorio login` on the same machine first. The MCP
server reads the same `~/.actorio/config.json` the CLI writes.

## Config file

Location: `~/.actorio/config.json`, mode `0600`.

Fields:

- `base_url` — the Actorio instance this token was issued for.
- `token` — the bearer token (`act_...`).
- `token_label` — the label supplied at `login` time.

Delete it with `actorio logout`.

## Pagination

Search commands take `--limit` (results per request; server default 20 for
products/favorites/amazon, 16 for reverse, max 100) and `--offset` (skip
this many results, default 0). When using `--json`, check
`pagination.has_more` to decide whether to fetch more by increasing
`--offset` by `--limit`.
