Skip to content
appctl

appctl doctor

appctl doctor takes .appctl/schema.json (produced by appctl sync) and probes every HTTP tool against the live base URL. It is safe to run against production: the probe uses HEAD and OPTIONS where possible and falls back to small GET requests, never mutating verbs.

The guided appctl setup flow runs doctor --write for HTTP-like sources when it has enough information. Run doctor manually after changing a base URL, auth header, or synced routes.

Usage

Section titled “Usage”
Terminal window
appctl doctor [OPTIONS]
appctl doctor models [--provider <NAME>]

Options

Section titled “Options”
FlagDefaultWhat it does
--timeout-secs <SECS>10Per-request timeout.
--writeoffAfter probing, update provenance = "verified" in .appctl/schema.json for tools that returned anything other than 404 or a connection error.

What it probes

Section titled “What it probes”

For each Http tool in the schema, doctor tries:

Tool methodOrder it tries
GETHEAD → fallback GET
DELETEHEAD → fallback OPTIONS
POST / PUT / PATCHOPTIONS → fallback HEAD

The goal is to get a status code for the route without actually executing the side effect. A 200, 401, 403, 405, or 5xx is still considered “reachable” for the purposes of provenance — it only means the route exists. Only 404 and connection errors are treated as not reachable.

Path placeholders ({id}, {Id}, {uuid}) are substituted with 1 or a zero-UUID so the probe has a real URL.

Scope

Section titled “Scope”

doctor covers HTTP tools in .appctl/schema.json. To exercise the LLM, use appctl chat with a short message — the model is called on the first turn. Mutating routes still use OPTIONS or HEAD before any fallback POST. The schema file stays read-only unless you pass --write.

Model checks

Section titled “Model checks”

appctl doctor models verifies the configured LLM provider path without executing application tools. Use it after appctl init, after changing provider config, or when chat fails before any tool call.

Terminal window
appctl doctor models
appctl doctor models --provider openai

This is separate from route probing: appctl doctor checks the synced app surface, while appctl doctor models checks the model/provider connection.

--strict and provenance

Section titled “--strict and provenance”

The chat and serve loops accept a --strict flag that blocks any tool with provenance = "inferred". The only way to flip that flag to verified today is appctl doctor --write. Re-run it after every appctl sync in strict deployments.

Examples

Section titled “Examples”
Terminal window
# Probe every HTTP tool with the default 10s timeout.
appctl doctor


# Long-running routes or flaky APIs
appctl doctor --timeout-secs 30


# Record a verified snapshot after a clean run
appctl doctor --write


# Check provider/model connectivity
appctl doctor models

Output

Section titled “Output”
┌─ doctor
│  Safe HTTP probes for each tool in the synced schema (HEAD/OPTIONS/GET)
│
│  app directory  /Users/you/project/.appctl
│  Target: base URL https://api.example.com
│
│  tool                             method path                                       HTTP  verdict
│  ────────────────────────────────────────────────────────────────────────────────────────────────
│  users.list                       GET    /users                                        200  reachable
│  users.create                     POST   /users                                        204  reachable
│  users.get                        GET    /users/1                                      200  reachable
│  orders.refund                    POST   /orders/1/refund                              404  missing (404)
│
│  Tip: Pass --write to mark reachable (non-404) routes as provenance=verified.
Section titled “Related”