wilfie 2026.3.1.1

Wilfie public API wrapper CLI

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:

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

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

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:

python -m wilfie auth refresh

• Logout/revoke:

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:

python -m wilfie auth status

API Key Mode

Set API key and declared scopes:

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

Show masked API key state:

python -m wilfie auth api-key show

Clear API key:

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:

# 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