Commit Graph
1 Commits
Author SHA1 Message Date
coder[bot]andNick Vigilante c9ea1914a6 feat(cli): add phase 1 coder exp api command with httpie-style request items (#31427)
Adds a hidden `coder exp api` command that covers **Phase 1 only** of
the "Simplified API Access via CLI" RFC, using httpie-style request
items as RFC reviewers asked. It's a smaller alternative to #31406,
which also ships Phase 3 (`--jq`, `--paginate`, `--verbose`).

```
coder exp api [METHOD] <path> [REQUEST_ITEM ...]
```

| Item | Meaning |
|---|---|
| `Name:value` | Request header |
| `Name:` | Remove a request header, such as the default `Content-Type`
|
| `name==value` | Query parameter, appended to any query already in the
path |
| `name=value` | JSON string field |
| `name:=json` | Raw JSON field (number, bool, null, array, object) |
| `name=@file` / `name:=@file` | String or JSON field read from a file,
`-` for stdin |

- The path is relative to `/api/v2/`. A path that starts with `api/` or
`/api/` is used as given, for example `/api/experimental/chats`.
- METHOD is optional. The first argument counts as a method only when it
matches a known HTTP method, so paths like `users` still work. The
default is GET, or POST when there are data items or `--input`.
- `--input <file|->` sends a raw body. It can't be combined with data
items, the combination is rejected before any file or stdin is read, and
stdin is never read implicitly.
- There's no `-H` flag. Per-request headers are `Name:value` items, and
the existing global `--header` / `--header-command` flags still apply
because the command uses `r.InitClient`. Their values are sent in
addition to header items.
- Auth, TLS and the deployment URL all come from the existing CLI
session (`CODER_URL`, `CODER_SESSION_TOKEN`, or `coder login` state).
There's no new auth logic.
- The command refuses absolute URLs and `.` or `..` path segments,
including percent-encoded ones, so the token only goes to API routes on
the configured deployment. It warns (but doesn't block) when that URL is
plain HTTP to a host that isn't loopback.
- httpie forms that would mean something different here are rejected
rather than sent literally: `==@` and `:@` file separators, nested JSON
field names such as `a[b]=c`, and a `Host` item.
- It prints the raw response body. On 4xx/5xx it prints the body and
exits non-zero with the Coder error, plus an API reference hint when the
route doesn't exist.
- No new dependencies. `go.mod` and `go.sum` are unchanged.

**Left out on purpose:** `--jq`, `--paginate`, `-i/--include`,
request/response logging, and gh-style `-X`/`-f`/`-F`/`-H` flags.

**Decisions still open in the RFC:**
- Whether httpie syntax is final.
- Whether `--paginate`/`--jq` belong in Phase 1 at all. The RFC lists
them under both the initial requirements and Phase 3.
- An explicit `GET` with data items sends a JSON body, which is what
httpie does.

The new code is `cli/exp_api.go`, plus a one-line registration in
`cli/root.go`. Tests are in `cli/exp_api_internal_test.go` (parsing) and
`cli/exp_api_test.go` (integration).

Tests run in the workspace:
- `go test ./cli/ -run
'TestExpAPI|TestAPIURLIsInsecure|TestAPIRequestPath|TestSplitAPI|TestParseAPIRequestItems'`,
also with `-race` plus `TestCommandHelp`
- `go vet ./cli/`
- `golangci-lint run ./cli/...`
- `make lint/go/new-code`, and `make lint/go` through the pre-commit
hook

> [!NOTE]
> This PR was generated by Coder Agents on behalf of @nickvigilante.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
2026-11-04 15:18:08 -05:00