Metadata-Version: 2.4
Name: tool4seller-cli
Version: 1.1.0
Summary: Tool4Seller CLI for sales, advertising, inventory, and profit workflows
Project-URL: Homepage, https://www.tool4seller.com/
Project-URL: API Documentation, https://das-server.tool4seller.com/api/v3/api-docs/v2
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: requests>=2.28
Requires-Dist: packaging>=23.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# Tool4seller CLI

Official Python CLI for Tool4seller sales, advertising, inventory, and profit workflows. It combines OAuth authentication, an OpenAPI-driven command surface, packaged AI-agent skills, and guarded advertising writes.

## Highlights

- Query sales, profit, inventory, inventory alerts, inbound shipments, reviews, and sales traffic.
- Analyze advertising performance by store, campaign, SKU, ASIN, search term, keyword target, and product target.
- Search campaigns and targets with attribute and aggregated metric filters.
- Retrieve Amazon target and bid recommendations for Sponsored Products, Sponsored Brands, and Sponsored Display.
- List, create, and update campaigns, ad groups, ads, keywords, negative keywords, product targets, and negative targets.
- Inspect every request contract from the bundled Tool4seller OpenAPI schema.
- Install workflow skills for Codex, Claude, WorkBuddy, Agents, and Doubao.
- Protect every state-changing request with validation and an exact one-time confirmation.

## Install

```bash
pip install tool4seller-cli
```

## First-Time Setup

After installation, install the packaged skills into your assistant environment:

```bash
tool4seller skills install
```

Then authenticate again:

```bash
tool4seller auth login
```

After authentication succeeds, you can ask sales, advertising, inventory, and profit questions such as:

- "Show me yesterday's sales."
- "Analyze advertising ACOS for the last 7 days."
- "Find high-spend campaigns with no orders."
- "Get Amazon bid recommendations for these targets."
- "Create a Sponsored Products campaign."
- "Find low-stock SKUs."

## Usage

```bash
tool4seller --version
tool4seller version --check
tool4seller auth login
tool4seller auth status
tool4seller schema list
tool4seller schema show sales.list-sales
tool4seller sales list-sales --start-date 2026-06-01 --end-date 2026-06-07
```

Production is the default API environment. Use the named test environment only for explicit ITE testing:

```bash
tool4seller --env test auth login
tool4seller --env test campaigns list --store-id SELLER:MARKETPLACE
```

## Advertising Search and Recommendations

Operations with an OpenAPI JSON request body accept either inline JSON or a UTF-8 JSON file:

```bash
tool4seller advertising-targeting-performance search-keyword-targets \
  --data '{"storeId":"SELLER:MARKETPLACE","startDate":"2026-08-01","endDate":"2026-08-07"}'

tool4seller advertising-targeting-performance search-asin-targets \
  --data-file request.json
```

Recommendation APIs are read-only POST operations and do not require write confirmation:

```bash
tool4seller advertising-targeting-performance get-target-recommendations \
  --data-file target-recommendation-request.json

tool4seller advertising-targeting-performance get-bid-recommendations \
  --data-file bid-recommendation-request.json
```

Inspect the exact nested filters and request fields before preparing a payload:

```bash
tool4seller schema show advertising-campaign-performance.search-campaigns
tool4seller schema show advertising-targeting-performance.get-target-recommendations
tool4seller schema show advertising-targeting-performance.get-bid-recommendations
```

## Advertising Management

Stable resource commands keep management workflows readable:

```bash
tool4seller campaigns list --store-id SELLER:MARKETPLACE
tool4seller campaigns create --data-file campaign-create.json
tool4seller campaigns update --data-file campaign-update.json

tool4seller ad-groups create --data-file ad-group-create.json
tool4seller ads create --data-file ad-create.json
tool4seller keywords create --data-file keyword-create.json
tool4seller targets update --data-file target-update.json
```

Equivalent `list`, `create`, and `update` commands are exposed where supported for ad groups, ads, keywords, negative keywords, targets, and negative targets. Portfolios currently expose `list` only.

## Write Confirmation

Every state-changing API request requires an exact, one-time customer confirmation. For operations in the bundled schema, the first invocation validates the payload and returns `confirmation_required` with a change preview, payload fingerprint, and ten-minute one-time confirmation token without sending the write request. Unknown non-GET requests still fail closed as writes, but cannot receive schema validation.

After the customer reviews and explicitly confirms that exact preview, execute the unchanged command with the returned one-time confirmation token. Replace the placeholders below with the same method, path, and payload used for the preview:

```bash
tool4seller api PATCH /api/v2/WRITE_PATH \
  --data-file write-request.json \
  --confirm-write confirm_<one-time-token>
```

The token is consumed before the network request and cannot be replayed. Changing the environment, path, parameters, or request body also invalidates it. Unknown non-GET requests fail closed as writes. A partially successful batch must be reviewed item by item and must not be retried as a complete batch.

If a confirmed write returns `write_outcome_unknown`, the server may have applied it before the response failed. Do not retry the request. Read the affected resources and reconcile every item first; for create operations that cannot be reconciled unambiguously, stop instead of risking duplicates.

## Agent Skills

Install the packaged Tool4seller skills into the Tool4seller-managed skill store:

```bash
tool4seller skills install
```

By default, this installs the packaged skills under `~/.tool4seller/skills/` and links them into existing agent directories for Codex, Claude, WorkBuddy, Agents, and Doubao. Missing agent directories are not created by the default install.

Manage links explicitly:

```bash
tool4seller skills link --agent doubao
tool4seller skills link --all
tool4seller skills unlink --agent claude
tool4seller skills unlink --all
```

Install skills into the current project's `.skills/` directory:

```bash
tool4seller skills install --local
```

To install into a custom directory, use:

```bash
tool4seller skills install --destination ~/.codex/skills
```

## Upgrade

```bash
tool4seller update
tool4seller update --yes --target-version <latestVersion>
pip install -U tool4seller-cli
```

`tool4seller update` checks the latest PyPI release and prints an upgrade command pinned to that exact version using the Python interpreter that runs the current CLI. After reviewing that version, pass it to `tool4seller update --yes --target-version <latestVersion>`. When the target version is already installed, the command performs no installation.
