Your first app

This tutorial takes a small CLI from an empty directory to an executable you can move to another machine with the same operating system and architecture. Install v0.7.2 for this workflow; v0.6.0 predates these project commands. Confirm that kipferl --version reports v0.7.2 and kipferl new --help lists --template before continuing. A development checkout also supports the workflow.

Create a working project

kipferl new hello --template cli
cd hello

You now have hello.py, a README.md, a starter test in tests/test_app.py, editor stubs under .kipferl/stubs, a pyrightconfig.json, and project defaults:

{
  "entry": "hello.py",
  "output": "dist/hello",
  "assets": [],
  "tests": ["tests"]
}

The CLI template includes argument parsing and --help. Explore it before making changes:

kipferl run -- --help

For an API client or a guided interactive app, choose --template api or --template interactive when creating the project. Each comes with runnable code and a test, and needs no pip install. The generated README explains its arguments. See project commands for the full layout.

Develop and test

kipferl dev

Kipferl runs hello.py immediately. Open it in your editor, change its greeting, and save: the app restarts. The watcher stays open after the app exits and restores terminal settings after interactive prompts. Stop it with Ctrl-C. Use kipferl run for one execution, or kipferl dev --clear for a fresh screen on each restart. Configuration and template files are watched too.

Run the starter test and add assertions for your changes:

kipferl test

Tests are ordinary Python scripts named test_*.py. Each runs in a separate process; failed assertions or other nonzero exits make the command fail. There is no pytest dependency. Run the tests after each meaningful change and before shipping. See the development reference for extra watch paths and application arguments.

Ship one executable

kipferl build
./dist/hello --help

The default build embeds the runtime and your application's local Python modules. It reports unsupported imports before producing a successful build. You do not need a Rust compiler. Try the result from a directory containing only the executable:

mkdir -p /tmp/kipferl-hello-demo
cp dist/hello /tmp/kipferl-hello-demo/hello
cd /tmp/kipferl-hello-demo
./hello --help

The recipient needs no Kipferl or Python installation. Choose a different target when the recipient has a different operating system or CPU:

# Run this from your hello project
kipferl build --target linux-x86_64 -o dist/hello-linux

Data files need an explicit assets entry or --asset; read them relative to __file__ so they work after packaging. See portable packaging for a complete example, dependency limits, and isolation checks.

Build your second app

Use a tested recipe to process CSV, fetch a JSON API, inspect a source directory, or generate a report. Keep the generated editor configuration for autocomplete, and enable shell completion for commands and options.