Metadata-Version: 2.4
Name: wilfie
Version: 2026.3.1.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 Public CLI (OAuth + API Wrapper)

This document describes the public `wilfie` CLI package implemented in this
repository under `wilfie_cli/`.

The public CLI is intentionally separate from the internal operator CLI
(`wilfie_fastapi_app/src/cli.py` + `./run` wrappers). The public CLI only
calls FastAPI `/api/v2` endpoints.

## Overview

- Entry points:
  - `python -m wilfie --help`
  - `python -m wilfie_cli --help`
- Customer install (published builds):
  - `uv tool install wilfie`
- Default API host:
  - `https://wilfie.ai`
- Auth modes:
  - OAuth/OIDC device flow (recommended for humans)
  - API key mode (`X-API-Key`) for machine/agent usage
- Output modes:
  - `--output table` (default)
  - `--output json`

## OAuth Login Flow

Use OAuth device flow:

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

If you override the API URL, pass host only (not `/api/v2`), for example:

```bash
python -m wilfie --base-url https://wilfie.dev auth login
```

The CLI requests a device code via:

- `POST /api/v2/oauth/device_authorization`

Then polls:

- `POST /api/v2/oauth/token` with
  `grant_type=urn:ietf:params:oauth:grant-type:device_code`

On success, access/refresh tokens are persisted in the CLI profile.

### Refresh and logout

- Refresh:

```bash
python -m wilfie auth refresh
```

- Logout/revoke:

```bash
python -m wilfie auth logout
```

Logout calls `POST /api/v2/oauth/revoke` when a refresh token is present, then
clears local OAuth credentials.

Check local auth/session state:

```bash
python -m wilfie auth status
```

## API Key Mode

Set API key and declared scopes:

```bash
python -m wilfie auth api-key set \
  --api-key '<key>' \
  --scope wms.read \
  --scope workflows.read
```

Show masked API key state:

```bash
python -m wilfie auth api-key show
```

Clear API key:

```bash
python -m wilfie auth api-key clear
```

The CLI performs local scope preflight for API-key mode and fails closed when
required scope cannot be proven.

## Command Surface

### Workspaces (OAuth mode)

- `wilfie workspaces list`
- `wilfie workspaces get <workspace_code>`
- `wilfie workspaces roles <workspace_code>`
- `wilfie workspaces permission-definitions <workspace_code>`

### Workflows (OAuth or API key)

- `wilfie workflows list --workspace <workspace_code>`
- `wilfie workflows runs --workspace <workspace_code> --workflow-id <id>`
- `wilfie workflows execute --workspace <workspace_code> --workflow-id <id>`

### WMS (OAuth or API key)

- `wilfie wms facilities --workspace <workspace_code>`
- `wilfie wms skus --workspace <workspace_code>`
- `wilfie wms query --workspace <workspace_code> --path <endpoint_path> [--param key=value ...]`

#### WMS debug queries

Use `wms query` to hit any read-only WMS endpoint so you can debug
issues without waiting for a dedicated command wrapper.

Examples:

```bash
# Relative WMS path
wilfie wms query \
  --workspace acme \
  --path facility-locations/search \
  --param query=A-01 \
  --param limit=25

# Full API path copied from logs (same command still works)
wilfie wms query \
  --workspace acme \
  --path /api/v2/workspaces/acme/wms/inbound-receipts/123/items \
  --param limit=100
```

## Permission behavior

- Workspace-scoped commands require explicit `--workspace`.
- OAuth mode performs workspace preflight using:
  - `GET /api/v2/workspaces/{workspace_code}`
- API-key mode checks locally declared scopes before request dispatch.
- Server-side RBAC and API key scope checks remain source-of-truth.

## Profile storage

Profiles are stored in:

- `$WILFIE_CLI_CONFIG_PATH` when set
- otherwise `~/.config/wilfie/cli.json`

When available, keyring backends are used for secrets (`access_token`,
`refresh_token`, `api_key`) with file fallback.

## Release pipeline

CLI packaging and publish automation is defined in:

- `.github/workflows/cli_publish.yml`

Behavior:

1. On pull requests to `development` with `wilfie_cli/**` changes, CI runs
   CLI tests/build and publishes a private dev build to AWS CodeArtifact.
2. On push to `main` with `wilfie_cli/**` changes, CI runs CLI tests/build and
   publishes a production build to PyPI via trusted publishing (OIDC).
3. Version is generated in CI at publish time (CalVer format):
   - prod: `YYYY.M.D.N`
   - dev: `YYYY.M.D.N.dev<run><attempt>`
4. The CI version bump is not committed back to `pyproject.toml`.

Required repository settings:

- Secrets:
  - `AWS_ACCESS_KEY_ID`
  - `AWS_SECRET_ACCESS_KEY`
  - `AWS_DEFAULT_REGION` (fallback for dev publish region)
- Variables:
  - `CLI_DEV_CODEARTIFACT_DOMAIN`
  - `CLI_DEV_CODEARTIFACT_REPOSITORY`
  - `CLI_DEV_CODEARTIFACT_REGION` (optional if `AWS_DEFAULT_REGION` is set)
  - `CLI_DEV_CODEARTIFACT_DOMAIN_OWNER` (optional, needed for cross-account)

PyPI trusted publisher settings:

- Configure pending publisher (or project publisher after first release) with:
  - PyPI project name: `wilfie`
  - Owner: `gavincliffe`
  - Repository name: `wilfie-flask-app`
  - Workflow name: `cli_publish.yml`
  - Environment name: `pypi`
