# Hoko CLI

Hoko CLI is a JSON command-line client for the Hoko API. Its release binary bundles its runtime.

## Install

- macOS and Linux: https://cli.hoko.to/install.sh
- Windows PowerShell: https://cli.hoko.to/install.ps1
- Manual archives: https://cli.hoko.to/#downloads

## Authentication

- Human users: `hoko auth login --workspace-id <workspace_id>` uses OAuth and stores credentials in the operating system credential store.
- Automation: set `HOKO_API_KEY`.
- Check state: `hoko auth status`.
- Select a workspace: `hoko workspace select <workspace_id>`.

## Commands

`hoko <resource> list|create|update|delete [--body JSON]`

Resources: `links`, `collections`, `tags`, `partners`, `utm-templates`, `customers`, `analytics`, `events`, `journeys`, `webhooks`, `usage`, `keys`, `lead`, `sale`.

Webhooks also support `verify`, `test`, and `disable`. Deliveries support `list` and `resend`.

Resource commands return JSON. Help and version commands return text. Errors use stderr and non-zero exit codes.

## Links

- Full CLI reference: https://cli.hoko.to/llms-full.txt
- API documentation: https://docs.hoko.to/llms.txt
- Help center: https://help.hoko.to/llms.txt
- OpenAPI: https://api.hoko.to/openapi.json

## Global options

- `--api <origin>`: use another API origin.
- `--issuer <origin>`: use another OAuth issuer.
- `--body <JSON>`: provide a JSON request body.
- `--show-secrets`: request secret fields when the operation allows it.

## Authentication commands

| Command | Result |
| --- | --- |
| `hoko auth login --workspace-id <workspace_id>` | Opens the Hoko OAuth consent flow and stores the resulting credential. |
| `hoko auth status` | Reports whether OAuth or an API key is available. |
| `hoko auth refresh` | Refreshes the stored OAuth credential. |
| `hoko auth logout` | Revokes the stored OAuth credential and removes local state. |

## Resource commands

| `links` | List, create, update, and delete links. |
| `collections` | Manage link collections. |
| `tags` | Manage tags. |
| `partners` | Manage partner records. |
| `utm-templates` | Manage reusable UTM templates. |
| `customers` | Manage customers. |
| `analytics` | Read click analytics. |
| `events` | Read recorded lead and sale events. |
| `journeys` | Read journey measurements. |
| `webhooks` | Manage endpoints and delivery actions. |
| `usage` | Read workspace usage. |
| `keys` | Manage API keys. |
| `lead` | Record a lead conversion. |
| `sale` | Record a sale conversion. |

The generic operation interface is useful when a resource has a named engine operation:

```sh
hoko operations list
hoko operation measurement.events.list --body '{}'
```

Webhook actions:

```sh
hoko webhooks verify --webhook-id <webhook_id>
hoko webhooks test --webhook-id <webhook_id> --test-intent-id <intent_id>
hoko webhooks disable --webhook-id <webhook_id>
```

## Exit codes and errors

- `0`: command succeeded.
- `1`: request or server failure.
- `2`: invalid command, option, or JSON input.
- `3`: missing credential or local credential-store failure.

The CLI does not retry writes automatically. Retry only after checking whether the previous request completed.

## Deployment origins

- API: https://api.hoko.to
- OAuth issuer: https://auth.hoko.to
- API reference: https://docs.hoko.to
- Help: https://help.hoko.to

Use the origin flags for staging or local work. Do not put a path, query string, fragment, username, or password in an origin.