Metadata-Version: 2.4
Name: wilfie
Version: 2026.9.12.1
Summary: Wilfie public API wrapper CLI
Author: Wilfie
Project-URL: Homepage, https://wilfie.ai
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"

# Wilfie CLI

Wilfie is a command-line client for Wilfie APIs.

Use it to authenticate and run workspace, workflow, and WMS commands from your terminal.

Workspace order, stock and general analytics reads share their API request code
with Wilfie's MCP tools. Start analytics with
`wilfie wms analytics config --workspace <workspace_code>` to discover available
metrics, supported filters, periods and dimensions, then use `summary`,
`timeseries`, `dimension-members` or `leaderboards`. Metric availability and
currency readiness come from the workspace; revenue is not assumed to exist.

## Install

```bash
uv tool install wilfie
```

Or with `pip`:

```bash
pip install wilfie
```

## Quickstart

Login with device flow:

```bash
wilfie auth login --client-id wilfie-cli
```

Check auth status:

```bash
wilfie auth status
```

List workspaces:

```bash
wilfie workspaces list
```

Run a WMS query:

```bash
wilfie wms query \
  --workspace <workspace_code> \
  --path facility-locations/search \
  --param query=A-01 \
  --param limit=25
```

Inspect fulfillment document lineage:

```bash
wilfie wms documents lineage \
  --workspace <workspace_code> \
  --kind fulfillment_order \
  --document-id <fulfillment_order_id> \
  --line-id <line_id> \
  --max-depth 8
```

Resolve a barcode and inspect tote outbound context:

```bash
wilfie wms barcodes resolve \
  --workspace <workspace_code> \
  --facility-id <facility_id> \
  --barcode <scan_value>

wilfie wms containers outbound-context \
  --workspace <workspace_code> \
  --container-id <container_id>
```

Run Shopify outbound reconcile (manual trigger):

```bash
wilfie wms reconcile outbound \
  --workspace <workspace_code> \
  --integration-connection-id <integration_connection_id> \
  --order-id gid://shopify/Order/123 \
  --dry-run
```

Analyze live-selling performance after ignoring orders less than $8:

```bash
wilfie --output json live-selling orders \
  --workspace <workspace_code> \
  --period this_month \
  --order-total-less-than 8
```

Download order-level live-selling data for local analysis:

```bash
wilfie live-selling orders \
  --workspace <workspace_code> \
  --period this_month \
  --order-total-less-than 8 \
  --download-file live-selling-orders.csv
```

List open WMS issues for a facility:

```bash
wilfie wms issues list \
  --workspace <workspace_code> \
  --facility-id <facility_id> \
  --status open
```

Recompute WMS issues for a facility (admin/owner access required):

```bash
wilfie wms issues recompute \
  --workspace <workspace_code> \
  --facility-id <facility_id> \
  --dry-run
```

This package provides workspace functionality in local, dev and production
environments. Platform infrastructure administration is distributed separately.

## Supplier Offer Recovery

Use these commands in order to restore PIM details from the stored Shopify mirror,
fill missing offer catalog fields, and reapply the offer's pricing:

```bash
wilfie supplier-offers update-pim --workspace <workspace_code> --offer-id <offer_id>
wilfie supplier-offers hydrate --workspace <workspace_code> --offer-id <offer_id>
wilfie supplier-offers promote-pricing --workspace <workspace_code> --offer-id <offer_id>
```

Update PIM also copies mirror prices into PIM, so run Pricing Only last. Hydrate
preserves offer pricing and supports `--dry-run`; its default mode fills blanks.
Pricing Only requests pricing updates without publishing catalog fields or inventory.
The queued commands wait for completion unless `--no-wait` is supplied. Review
the returned warnings and per-product results for skipped or failed updates.
All three commands require OAuth login. Update PIM and Hydrate require workspace
admin access; Pricing Only requires editor access.

## Xero Integration

Every Xero command requires the exact workspace and integration connection. The
CLI calls Wilfie's workspace APIs and never stores Xero tokens or chooses a tenant
implicitly. These commands use Wilfie OAuth login; API-key-only profiles are not
accepted by the current workspace Xero endpoints.

```bash
wilfie integrations connections list --workspace <workspace_code> --integration-type xero
wilfie integrations xero settings get --workspace <workspace_code> --connection-id <connection_id>
wilfie integrations xero accounting selectors --workspace <workspace_code> --connection-id <connection_id>
wilfie integrations xero accounting mappings list --workspace <workspace_code> --connection-id <connection_id>
wilfie integrations xero contacts sync --workspace <workspace_code> --connection-id <connection_id> --mode full
wilfie integrations xero contacts list --workspace <workspace_code> --connection-id <connection_id> --unmapped-only
wilfie integrations xero contacts create-supplier --workspace <workspace_code> --connection-id <connection_id> --xero-contact-id <contact_id> --expected-payload-hash <sha256> --confirm
wilfie integrations xero invoices list --workspace <workspace_code> --connection-id <connection_id> --invoice-type ACCPAY
wilfie integrations xero invoices sync --workspace <workspace_code> --connection-id <connection_id> --mode full
wilfie integrations xero invoices attachments --workspace <workspace_code> --connection-id <connection_id> --xero-invoice-id <xero_invoice_id>
wilfie integrations xero invoices import --workspace <workspace_code> --connection-id <connection_id> --xero-invoice-id <xero_invoice_id> [--attachment-id <attachment_id>]
```

Use `accounting mappings set` to configure GL and tax selections. Run `contacts
sync --mode full` once for the initial contact mirror; Xero CONTACT webhooks then
maintain it, with no scheduled provider sync. Use `contacts list` before either
creating a guarded Wilfie supplier from a reviewed Xero contact or deliberately
linking an existing supplier with `supplier-mappings link`. Supplier `ensure` can
create or update a Xero contact with approved Wilfie bank details and therefore
requires `--confirm`.

Run `invoices sync --mode full` once for the initial invoice mirror. Xero Invoice
webhooks maintain it afterward; use `--mode targeted --xero-invoice-id <id>` for
one-record repair or rerun full only for a diagnosed wider repair. No Xero CLI
command creates a recurring provider sync. Use `invoice-mappings candidates` to compare an existing Wilfie AP invoice with
same-number Xero bills, then `invoice-mappings link` with the selected exact-match
Xero InvoiceID. Local invoice list/detail is the default; `invoices live-list` is
the explicitly bounded provider read. `invoices sync` queues the durable mirror
operation and follows it unless `--no-wait` is supplied.

For a supplier bill created in Xero first, use `invoices attachments` to inspect
the original files, then `invoices import` to send the selected PDF through the
same detailed extraction and review workflow as a Wilfie drag-and-drop upload.
The import is idempotent for the Xero InvoiceID, does not retry the POST after a
network error, and follows the extraction operation unless `--no-wait` is used.

## Common Commands

- `wilfie auth login`
- `wilfie auth refresh`
- `wilfie auth logout`
- `wilfie workflows list --workspace <workspace_code>`
- `wilfie workflows runs --workspace <workspace_code> --workflow-id <id>`
- `wilfie workflows run-detail --workspace <workspace_code> --workflow-id <id> --run-id <id>`
- `wilfie workflows execute --workspace <workspace_code> --workflow-id <id>`
- `wilfie live-selling orders --workspace <workspace_code> --period this_month --order-total-less-than 8`
- `wilfie wms facilities --workspace <workspace_code>`
- `wilfie wms skus --workspace <workspace_code>`
- `wilfie wms documents list --workspace <workspace_code> --kind sales_order [--search-query <query>]`
- `wilfie wms documents list --workspace <workspace_code> --kind fulfillment_order`
- `wilfie wms documents detail --workspace <workspace_code> --kind fulfillment_order --document-id <id>`
- `wilfie wms documents lineage --workspace <workspace_code> --kind fulfillment_order --document-id <id> --line-id <id>`
- `wilfie wms barcodes resolve --workspace <workspace_code> --facility-id <facility_id> --barcode <scan_value>`
- `wilfie wms containers outbound-context --workspace <workspace_code> --container-id <container_id>`
- `wilfie wms issues list --workspace <workspace_code> [--facility-id <facility_id>] [--status <open|ignored|resolved>]`
- `wilfie wms issues recompute --workspace <workspace_code> [--facility-id <facility_id>] [--scope <scope>] [--dry-run]`
- `wilfie wms reconcile outbound --workspace <workspace_code> --integration-connection-id <id> [--order-id <shopify_order_id>] [--fulfillment-order-id <shopify_fo_id>] [--dry-run]`
- `wilfie integrations xero settings get --workspace <workspace_code> --connection-id <connection_id>`
- `wilfie integrations xero supplier-mappings get --workspace <workspace_code> --connection-id <connection_id> --supplier-company-id <supplier_id>`
- `wilfie integrations xero invoice-mappings candidates --workspace <workspace_code> --connection-id <connection_id> --invoice-id <wilfie_invoice_id>`
- `wilfie integrations xero invoices list --workspace <workspace_code> --connection-id <connection_id>`

## Configuration

- Default API host is `https://wilfie.ai`.
- Use `--base-url` to target another environment.
- Output modes: `--output table` (default), `--output json`.

## Links

- Homepage: <https://wilfie.ai>
- Documentation: <https://github.com/gavincliffe/wilfie-flask-app/tree/main/docs>
