CLI Reference

clq init

Scaffolds a new MCP server project. If you omit the project name, CLQ prompts you for one interactively. The name must be lowercase alphanumeric with hyphens (^[a-z0-9][a-z0-9-]*$) — this is validated before any files are written.

CLQ writes the project into a new subdirectory of your current directory and refuses to write outside it — path traversal attempts (e.g. ../../escape) are rejected at the name-validation step before any filesystem access.

What gets created

The generated template builds and runs without any edits. The starter tool file has a real, non-empty description so it satisfies CLQ's mandatory-description check immediately — the project compiles before you've written a word.

Flags

clq add

Adds a new tool file to the current project's src/tools/ directory. The tool name follows the same slug rules as the project name. CLQ walks up from your current directory looking for clq.config.ts as the project marker — you can run this from any subdirectory inside a project. The walk is bounded to 10 levels, so a stray invocation outside a project fails fast with a clear error instead of scanning the disk.

Generated file

import { defineTool } from "@clq-sh/core"
import { z } from "zod"

export const searchRepos = defineTool({
  name: "search_repos",
  description: "TODO: describe what search-repos does and when an agent should call it.",
  input: z.object({
    query: z.string().describe("Search query"),
  }),
  handler: async ({ input, ctx }) => {
    // TODO: implement
    return {}
  },
})

The description placeholder is intentionally a real sentence, not a comment — it satisfies CLQ's mandatory-description check so the project builds immediately. Replace it before shipping.

clq dev

Starts a hot-reload dev server. CLQ delegates file watching to tsx watch, which handles TypeScript-aware watching and incremental re-execution. When a source file changes, the server restarts automatically.

Shutdown behavior: On Ctrl+C, CLQ sends a signal to the tsx child process and waits for it to exit before the parent process exits. This is deliberate — a dev CLI that exits immediately on Ctrl+C leaves the watcher (and the server it spawned) running as orphaned processes that hold ports and file locks. CLQ waits for the full process tree to exit before returning.

clq inspect

Launches a local web inspector: a browser UI where you can call your tools, inspect responses, and review the last 200 call log entries. The inspector uses a two-process design — the inspector server spawns your project's src/index.ts as a child process, communicates with it over stdio, and proxies tool calls through.

Security model

The inspector binds exclusively to 127.0.0.1 — never 0.0.0.0. Every request is gated by two independent checks in order: the Origin header is validated first (a mismatched Origin returns 403 before the server reveals anything about the token), then the x-clq-token header is checked (a missing or wrong token returns 401). A browser tab on a malicious page cannot forge the Origin header and is blocked outright.

All responses — tool lists, call results, and log entries — are passed through redactSecrets() before leaving the server. Any response field whose key name contains a known secret pattern (token, password, api_key, authorization, bearer, jwt, private_key, and 9 more) is replaced with "[REDACTED]" regardless of where the data came from.

Port behavior

CLQ defaults to port 7317. If that port is busy, it retries the next 5 incrementing ports (7318–7322) before failing with a clear error.

clq doctor

Runs three independent health checks on the current project and exits non-zero if any fail:

1. Config validation — loads clq.config.ts in a short-lived tsx subprocess, checks all declared env vars are present and the correct type. The config subprocess reports only { ok, message, fix } — the actual env var values never cross back to the CLI process.
2. Dependency check — confirms node_modules is installed.
3. Secret scan — scans source files for hardcoded secrets using hand-rolled regex patterns. Reports the file, line number, and a masked preview of the match (first 3 + last 2 characters; short values are fully starred). The real matched value is never stored, returned, or logged — the masking happens at the innermost scope and the raw value is immediately unreferenced.