You are working with Bell, a DSL for describing and executing HTTP API requests. Bell files use the `.bel` extension. ## Variables Assign strings, numbers, or booleans to variables. Use `{varName}` to interpolate into strings. ```bel apiKey = "my-secret-token" userId = 42 active = true url "https://api.example.com/users/{userId}" header "Authorization" "Bearer {apiKey}" GET ``` ## Request Building Build a request with these keywords before dispatching it with an HTTP method: - `url "..."` — full base URL - `path "..."` — appended to the base URL (use with environments) - `param "key" value` — query parameter; or `param varName` to use a variable as both key and value - `header "Key" "value"` — individual request header - `headers { "Key": "value", ... }` — set all headers at once - `body { ... }` — JSON request body (set with POST, PUT, PATCH) ## HTTP Methods Write a method keyword to dispatch the currently built request: ```bel url "https://api.example.com" path "/users" GET path "/users" body { "name": "Jane" } POST path "/users/42" body { "name": "Jane Doe" } PUT path "/users/42" body { "name": "Jane D." } PATCH path "/users/42" DELETE ``` ## Response After a request, `response` is set. Bell keeps a history of all responses. ```bel url "https://api.example.com/users" GET log response.status # HTTP status code log response.body # full response body log response.body.data.id # nested property log response.headers # response headers # Multiple requests: index past responses with response.[n] url "https://api.example.com/posts" POST log response.[0].status # status of the GET above log response.[1].body # body of the POST ``` ## Logging ```bel log response.body log url count = 42 log count ``` ## User Interaction `input("prompt")` — prompts the user at runtime; use as expression or inline: ```bel id = input("Enter user ID") param "id" id url "https://api.example.com/posts" body { "title": input("Post title"), "body": input("Post body") } POST ``` `warn` — asks for confirmation before continuing (stops execution if declined): ```bel # As expression: returns the value if confirmed prodUrl = warn "api.example.com" url "https://{prodUrl}/users" GET # As statement: shows a message and waits warn "You are about to delete a user. Proceed?" url "https://api.example.com/users/42" DELETE ``` ## Guards and Assertions `require expr` — pre-condition guard; stops before the request if falsy: ```bel require token require id url "https://api.example.com/posts/{id}" header "Authorization" "Bearer {token}" DELETE ``` `expect expr` — checks a condition after a request, logs pass/fail, continues: ```bel url "https://api.example.com/users" GET expect response.status === 200 expect response.body.data !== null ``` `assert expr` — like `expect`, but stops execution immediately if the check fails: ```bel url "https://api.example.com/users" GET assert response.status === 200 assert response.body.id !== null ``` ## Imports ```bel # Named import from JSON import requestBody from "./request-body.json" # Named imports from TypeScript (types, schemas) import { UserRequest, UserResponse } from "./types.ts" # Anonymous import — loads an environment config or .env file import "./env-config.json" import "./.env" ``` ## .env Files Bell can load `.env` files. The special key `BELL_URL` sets the base URL. ```bash # .env BELL_URL=https://api.example.com API_KEY=my-secret ``` ```bel import "./.env" path "/users" header "Authorization" "Bearer {API_KEY}" GET ``` ## Environments Define environments in a JSON config: ```json { "dev": { "url": "https://dev.api.example.com", "version": "v1" }, "prod": { "url": "https://api.example.com", "version": "v2" } } ``` ```bel import "./env-config.json" env "dev" | "prod" # prompts the user to choose # or: env "prod" # sets without prompting path "/{version}/users" GET ``` ## Runtime Validation `validate expr as TypeName` — checks that a value matches a TypeScript type at runtime: ```bel import requestBody from "./request-body.json" import { UserRequest, UserResponse } from "./types.ts" validate requestBody as UserRequest url "https://api.example.com/users" body requestBody POST validate response.body as UserResponse ``` ## Multi-file Workflows `run "file.bel"` — runs another Bell file inline; exported variables become available: ```bel # login.POST.bel url "https://api.example.com/login" body { "username": "user", "password": "pass" } POST token = response.body.token export token ``` ```bel # main.bel run "./login.POST.bel" # token is now available from the sub-file url "https://api.example.com/posts" header "Authorization" "Bearer {token}" GET ``` `export varName` or `export a, b, c` — marks variables to share with callers. ## Comments ```bel # Single-line comment # # Multi-line comment block # ``` ## File Naming Convention Files are conventionally named `..bel` (e.g. `login.POST.bel`, `users.GET.bel`). This is conventional, not enforced by the runtime. ## CLI Quick Reference ```bash bell run # run a file bell run -e prod # run with environment bell run --dry-run # validate without sending requests bell run --retry 3 # retry failed requests up to 3 times bell run --proxy http://proxy:8080 # route through a proxy bell run --insecure # skip TLS verification bell run --json # print last response body as JSON bell run --output response.json # save last response body to file bell # shorthand (no subcommand needed) bell test # run all .bel files as test suite bell test tests/ --reporter junit # JUnit XML output for CI bell test tests/ --bail # stop on first failure bell check # static analysis (JSON diagnostics) bell init # create a starter bell/ folder bell format # format a file bell postman # convert Postman collection bell openapi # convert OpenAPI 3.x spec to Bell files bell curl '' # convert a curl command to Bell bell har # convert a HAR export to Bell files bell config # show merged Bell config bell skill # print this skill reference bell skill --install # install as Claude Code slash command ```