Aller au contenu

Bibliothèques · Référence

HttpApi CLI

An Effect CLI generator using shared typed HttpApi operations, readable arguments and flags, and incremental NDJSON stream output.

Dernière mise à jour le 9 octobre 2026

Overview

httpapi-cli turns HttpApiAdapter.operations into grouped Effect CLI commands. makeHttpApiCli() is the only public export and returns { command, run }. Construct once, then call run(args); the CLI version comes from API metadata. The returned command can also be composed with Effect's native command APIs.

Names are normalized to kebab-case. Path parameters become positional arguments; query, header, and top-level body fields become typed flags. Flag types, required fields, descriptions, and enum choices come from the operation's derived JSON Schema. The operation's Effect schema validates assembled input and preserves payload transformations before execution through the generated HTTP client.

Install

shell
bunx shadcn@latest add @krak-stack/httpapi-cli

Installation And Imports

Install @krak-stack/registry and use the imports below. Alternatively, install @krak-stack/httpapi-cli with shadcn and use @/lib/httpapi-cli and @/lib/httpapi-adapter. Registry item identifiers are not npm module paths.

Construct And Run Commands

Inside an application Effect program with HttpApiAdapter and platform CLI services provided:

ts
import { makeHttpApiCli } from "@krak-stack/registry/httpapi/cli";

const { run } = yield* makeHttpApiCli();
yield* run(args);

Annotate the API with OpenApi.annotations({ title, version, description }) to configure CLI identity and help text. For a standalone Node entry point, install @effect/platform-node matching your Effect version:

ts
import { NodeRuntime, NodeServices } from "@effect/platform-node";
import { Effect, Layer } from "effect";
import { FetchHttpClient } from "effect/http";
import { makeHttpApiCli } from "@krak-stack/registry/httpapi/cli";
import { HttpApiAdapter } from "@krak-stack/registry/httpapi/adapter";
import { AppApi } from "@/api";

const adapterLayer = HttpApiAdapter.layer({
  api: AppApi,
  baseUrl: "https://example.com",
  methods: ["get", "post", "put", "patch", "delete"],
}).pipe(Layer.provide(FetchHttpClient.layer));

Effect.gen(function* () {
  const { run } = yield* makeHttpApiCli();
  yield* run(process.argv.slice(2));
}).pipe(
  Effect.provide(adapterLayer),
  Effect.provide(NodeServices.layer),
  NodeRuntime.runMain,
);

Use the corresponding Effect platform services and runtime for Bun. Process arguments, platform services, error reporting, and exit handling remain application-owned. There is no CLI service layer or custom process runner. HttpApiAdapter replaces the separate ApiClient and HttpApiSpec layers.

For API keys or session forwarding, replace FetchHttpClient.layer with an app-owned authenticated HTTP client layer. Use methods and include to select commands; selection does not replace server authorization or add an approval prompt.

Readable Arguments And Flags

For an examples.createExample endpoint with a path ID, boolean query, and body fields:

shell
app-api examples create-example example-123 \
  --include-archived \
  --display-name "CLI example" \
  --count 3 \
  --metadata '{"owner":"docs-team"}'

example-123 is positional, --include-archived is boolean, and --count 3 supplies a number. Only structured object and array values need JSON. Use --no-include-archived to supply false.

The CLI assembles { params, query, headers, body } internally. The generated client converts validated values into wire representations. Use generated --help and shell completions to discover names, required values, and enum choices.

Output And Errors

Normal results are encoded as JSON. Stream responses are printed incrementally as NDJSON. run(args) returns an Effect and propagates failures to its caller; use the application runtime to report errors and set the process exit status.

Dependencies
Packages and shadcn components required by this registry item.

Dependencies

Registry Dependencies