# Hoko CLI

Manage Hoko links, analytics, conversions, and webhooks from a terminal.

## Install

macOS or Linux:

```sh
curl -fsSL https://cli.hoko.to/install.sh | bash
```

Windows PowerShell:

```powershell
irm https://cli.hoko.to/install.ps1 | iex
```

The installer detects the operating system and CPU architecture. It installs a bundled binary, so Bun is not required. It adds the user install directory to your shell profile. Open a new terminal after installation. Use [direct downloads](https://cli.hoko.to/#downloads) to install the latest archive yourself.

## Authenticate

Use OAuth for a person:

```sh
hoko auth login --workspace-id <workspace_id>
hoko auth status
```

Use an API key for automation:

```sh
HOKO_API_KEY=hk_... hoko links list
```

OAuth credentials stay in the operating system credential store. API keys are read from `HOKO_API_KEY` and never printed in command output.

Find the workspace ID in the dashboard, then sign in:

```sh
hoko auth login --workspace-id <workspace_id>
```

Switch the selected workspace later:

```sh
hoko workspace select <workspace_id>
```

## Commands

Every resource accepts `list`, `create`, `update`, and `delete` where supported. Send JSON with `--body`.

| Command | Use |
| --- | --- |
| `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. |

Examples:

```sh
hoko links list
hoko links create --body '{"destination":"https://example.com"}'
hoko analytics list --take 50
hoko webhooks list
hoko deliveries list --webhook-id <webhook_id>
hoko deliveries resend --webhook-id <webhook_id> --event-id <event_id>
hoko operation measurement.events.list --body '{}'
```

Commands print JSON to stdout. Errors print JSON to stderr and return a non-zero exit code.

## Configuration

Set `HOKO_API_KEY` for non-interactive jobs. Use `--api` and `--issuer` to target a local or staging deployment during development:

```sh
hoko --api https://api.hoko.to links list
hoko --issuer https://auth.hoko.to auth login --workspace-id <workspace_id>
```

For local Portless development, use HTTP loopback origins:

```sh
hoko --api http://api.hoko.localhost:1355 --issuer http://auth.hoko.localhost:1355 auth login --workspace-id <workspace_id>
```

## Help and API reference

- [CLI command reference](https://cli.hoko.to/llms-full.txt)
- [Hoko API reference](https://docs.hoko.to/llms.txt)
- [Hoko help center](https://help.hoko.to/llms.txt)
- [OpenAPI document](https://api.hoko.to/openapi.json)

## Troubleshooting

If a command reports no credential, run `hoko auth login --workspace-id <workspace_id>` or set `HOKO_API_KEY`.

If a command targets the wrong workspace, run `hoko workspace select <workspace_id>`.

If OAuth opens the wrong deployment, pass `--issuer https://auth.hoko.to` and `--api https://api.hoko.to` together.

If a request returns a rate-limit error, wait for the `Retry-After` value and retry the same command. Do not create duplicate links while retrying.