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+
• For the simplest setup, run appctl setup from the demo folder after starting the app. The manual commands below are for users who want each step shown explicitly.

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. Guided setup or manual sync

Recommended:

appctl setup

Choose “OpenAPI document,” then enter:

• OpenAPI URL: http://127.0.0.1:8000/openapi.json
• Base URL: http://127.0.0.1:8000

Manual equivalent:

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 setup guides provider setup and sync; manual 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