Quickstart

This walkthrough uses examples/demos/openapi-fastapi. The same sync flow applies to any app that exposes an OpenAPI document.

Prerequisites

• appctl installed
• Python 3.11+
• A configured LLM provider; run appctl init (see appctl init). Accepting the optional app registration at the end adds this demo to ~/.appctl/apps.toml for global appctl chat / appctl serve.

1. Clone and start the demo

git clone https://github.com/Esubaalew/appctl.git
cd appctl/examples/demos/openapi-fastapi
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --host 127.0.0.1 --port 8000 &

Confirm the OpenAPI document is being served:

curl -s http://127.0.0.1:8000/openapi.json | head -c 60

Output:

{"openapi":"3.1.0","info":{"title":"appctl demo API","ve

2. Sync

In the same folder, point appctl at the live document:

appctl sync --openapi http://127.0.0.1:8000/openapi.json \
  --base-url http://127.0.0.1:8000 --force

Use --force if this directory already has a schema.json (e.g. you ran this before or copied the folder). Details.

Current output shape:

Sync complete
✔ Openapi: 1 resources, 1 tools written under .appctl

A new .appctl/schema.json describes the generated tool and .appctl/tools.json holds the flattened tool list the model sees.

3. Verify the tool is reachable

appctl doctor

Output:

tool                             method path         HTTP  verdict
create_widget_widgets_post       POST   /widgets      200  reachable

4. Talk to it

For a one-shot answer:

appctl run "create a widget named Demo"

Or get structured output for scripts:

appctl run --json "create a widget named Demo"

Or open the interactive REPL:

appctl chat
# appctl[app · openai]▶ create a widget named Demo

The agent picks create_widget_widgets_post, calls it, and prints the response. Every call is logged to .appctl/history.db.

appctl history --last 5

5. Run as a daemon (optional)

appctl serve --port 4242

See HTTP API for routes and WebSocket events.

Clean up

kill %1      # stop uvicorn
deactivate   # exit venv

Sequence summary

1. The demo app serves an OpenAPI document.
2. appctl sync maps operations to tools in .appctl/schema.json (here provenance=declared).
3. appctl doctor checks reachability against the live base URL.
4. appctl chat / appctl run send the tool list to the model and execute the calls it requests.

Next: other sync sources · provenance and safety · deploy / serve