CLI

Run

The very first thing you did in this guide was wf run app. Now that you've seen the whole stack, here's what that command actually arranges — and the few flags that change how your app comes up.

What run does

wf run <app> takes the name of an app config, reads app_configs/<app>.ini into the environment, sets a handful of runtime variables (the app name, host, port, log level) and launches your main.py as a child process. It streams the app's output to your console and tees it into a timestamped log file under logs/<app>/. Both an app config and a main.py have to exist, otherwise it tells you to create them first.

The flags

  • --host / -h — bind host. Default 127.0.0.1.
  • --port / -p — bind port. Default 8000.
  • --loglevel / -l — log verbosity (passed through to the log session). Default info.
  • --debug / -d — run in debug mode.
  • --interactive / -i — run with the interactive control menu.
terminal bash 
# Plain run on a custom port
wf run app -p 9000

# Debug mode with verbose logging
wf run app -d -l debug

Debug mode

The -d flag is what lights up the frontend developer experience. In debug mode the framework starts the Vite dev server, proxies it for hot module replacement, and rewrites your pages to pull assets from it — everything we described in the Frontend chapters. It also silences the insecure-session-cookie warning, since you're obviously developing.

 

Debug mode is not compatible with port 5173 — that one is reserved for the Vite dev server it manages for you. Pick any other port and you're fine.

Interactive mode

With -i, instead of streaming straight to your terminal, run drops you into a small control menu — restart, stop, start, join the live log, clear the log folder. It asks for host, port and debug up front if you didn't pass them. It's handy for babysitting a long-lived process during development.

 

Heads up: interactive mode does not behave properly on NT-based (Windows) systems in this alpha, due to how child processes are managed there. It's on the known-issues list on the overview page. On Windows, stick to a plain or debug run for now.

 

A plain (non-interactive) run forwards SIGINT and SIGTERM for you, so a clean Ctrl+C triggers the graceful shutdown sequence from the Lifecycle chapter: in-flight request finishes, shutdown hooks run, process exits.

That's the tour

From a single main.py to a fullstack runtime with batteries, modules and a managed frontend — and a CLI that scaffolds and runs the lot. You now have the whole map. For the precise surface of every class and function, the Reference is next.

Continue reading

From here you can continue straight with the Reference overview.