|
| 1 | +--- |
| 2 | +title: Direct SDK and HTTP access (advanced) |
| 3 | +description: When huly-cli doesn't have a flag for what you need — `huly api` and `huly ws` for raw, unvalidated passthroughs against your self-hosted Huly workspace. Advanced use only. |
| 4 | +--- |
| 5 | + |
| 6 | +# Direct SDK and HTTP access (advanced) |
| 7 | + |
| 8 | +> **Advanced only.** Two commands bypass every CLI safety check — ref resolution, type checking, cascade awareness, error mapping, and (for destructive calls) confirmation prompts: |
| 9 | +> |
| 10 | +> - **`huly api`** — raw HTTP passthrough. |
| 11 | +> - **`huly ws`** — raw WebSocket RPC. |
| 12 | +> |
| 13 | +> Treat them like raw SQL. Most workflows do not need them. If you find yourself reaching for them often for a pattern the CLI should expose, file an issue — that's a missing-feature signal. |
| 14 | +
|
| 15 | +When a CLI command doesn't exist for what you need, or the flag you need isn't exposed, talk to the server directly. Both commands are pass-through — they don't filter or transform the response. |
| 16 | + |
| 17 | +## Table of contents |
| 18 | + |
| 19 | +- [HTTP (`huly api`)](#http-huly-api) |
| 20 | +- [WebSocket (`huly ws`)](#websocket-huly-ws) |
| 21 | +- [When to use direct SDK access](#when-to-use-direct-sdk-access) |
| 22 | + |
| 23 | +--- |
| 24 | + |
| 25 | +## HTTP (`huly api`) |
| 26 | + |
| 27 | +```bash |
| 28 | +huly api GET /api/v1/version |
| 29 | +huly api GET /config.json |
| 30 | +huly api POST /api/v1/something --body '{"key":"value"}' |
| 31 | +huly api GET /api/v1/things --query foo=bar --query baz=qux |
| 32 | +huly api GET /api/v1/things --header "Authorization: Bearer ..." |
| 33 | +``` |
| 34 | + |
| 35 | +Available methods: `GET | POST | PUT | PATCH | DELETE`. The path |
| 36 | +is appended to the workspace's API URL. The CLI does not validate the path, method, body, or any custom headers — anything you send goes straight to the server. |
| 37 | + |
| 38 | +> **`Authorization` is not overridable.** The CLI always sets `Authorization: Bearer <resolved-token>` after merging your custom headers (`packages/cli/src/raw/api.ts:43-49`), so passing `--header "Authorization: Bearer …"` has no effect. All other custom headers pass through verbatim. |
| 39 | +
|
| 40 | +--- |
| 41 | + |
| 42 | +## WebSocket (`huly ws`) |
| 43 | + |
| 44 | +The Huly RPC protocol uses WebSocket for the SDK connection, but the |
| 45 | +raw `huly ws` command is **text JSON only**. Use it for direct |
| 46 | +method calls without opening the SDK's binary transport: |
| 47 | + |
| 48 | +```bash |
| 49 | +# findAll |
| 50 | +huly ws findAll '[{"_class":"tracker:class:Project"},{}]' |
| 51 | + |
| 52 | +# tx (raw transaction) |
| 53 | +huly ws tx '[{"_class":"core:class:TxCreateDoc",...}]' |
| 54 | +``` |
| 55 | + |
| 56 | +> `huly ws` accepts a single positional `<method>` followed by an |
| 57 | +> optional `[params]` argument that is a **JSON-encoded array of |
| 58 | +> positional parameters** for that method. On Huly 0.7.x the raw |
| 59 | +> socket dispatches a small whitelist: `findAll`, `tx`, `hello`, and |
| 60 | +> `ping`. Do not rely on `findOne`, `createDoc`, `updateDoc`, or other |
| 61 | +> SDK methods through this command — use the high-level commands |
| 62 | +> for writes, or `tx` for raw transaction payloads. |
| 63 | +> |
| 64 | +> The `tx` RPC supports every transaction type — `TxCreateDoc`, |
| 65 | +> `TxUpdateDoc`, `TxRemoveDoc`, `TxMixin`, `TxApplyIf`. Build the |
| 66 | +> payload directly; the CLI doesn't validate. **Confirm with the user before invoking** — raw RPC has no CLI confirmation prompt and bypasses every safety check. |
| 67 | +
|
| 68 | +--- |
| 69 | + |
| 70 | +## When to use direct SDK access |
| 71 | + |
| 72 | +- A command exists but doesn't expose the flag you need (rare). Use the high-level command with `--set key=value` first; reach for `huly ws` / `huly api` only when the field is not exposed at all. |
| 73 | +- A command exists but operates on a wrong sub-resource. |
| 74 | +- You're debugging and need to see the raw server response. |
| 75 | +- The CLI doesn't support the surface you need (use the SDK |
| 76 | + instead — see |
| 77 | + [Migration — from the SDK](../guides/migration.md#from-the-huly-sdk-typescript)). |
| 78 | + |
| 79 | +The commands pass through directly; the CLI handles auth and |
| 80 | +caching, not transformation. If you find yourself reaching for |
| 81 | +`huly ws` often, that's a signal the CLI should expose that surface |
| 82 | +natively — file an issue. |
| 83 | + |
| 84 | +**Do not use raw RPC to bypass `--yes`, validation, or duplicate-identifier checks.** Those refusals are intentional. |
0 commit comments