CLI reference

Command	What it does
crykit init <app_name>	Create a new application with routes, views, styles, and macOS packaging files
crykit dev	Compile and run an application with assets served from disk
crykit dev --watch	Run with source watching, live updates, and rebuilds
crykit build	Build an executable with embedded assets
crykit dist	Package a macOS .app bundle
crykit --help	List commands and options; also accepts -h
crykit --version	Print the CLI version; also accepts -v

Build the executable with Install the CLI.

init

Create and run a new application:

crykit init my_app
cd my_app
shards install
crykit dev --watch

<app_name> is the new directory name or path. Its parent directory must exist; the target must not already exist. init writes the project files; run shards install separately to install dependencies.

Generated file or directory	Purpose
shard.yml	Application target, CryKit dependency, and version
crykit.yml	Application name, entry, bundle ID, and development settings
src/main.cr	Application entry point
src/application/app.cr	Application configuration, menus, assets, and initial window
src/handlers/app_handler.cr	Routes
src/views/index.cr, src/views/templates/index.ecr	Starter view and template
src/layouts/main_layout.cr, src/layouts/templates/layout.ecr	Document layout
src/assets/main.css	Stylesheet
targets/dist.cr, targets/macos/	Distribution recipe, macOS target, and editable plist template
.gitignore, .editorconfig	Repository and editor defaults

dev

crykit dev
crykit dev --watch
crykit dev -f path/to/crykit.yml

Option	Default	Effect
-f FILE, --file FILE	./crykit.yml	Select the application configuration
-w, --watch	Off	Watch development.watch paths for live updates or rebuilds

Plain dev compiles and runs once, inherits terminal input/output, and returns the application's exit code. Assets stay on disk and asset hotreload is enabled.

With --watch, eligible CSS and template edits update the running app. Other source changes rebuild and restart it, resetting application state. A compiler error keeps the current app running until a later edit succeeds. See development updates for supported edits and watch behavior.

build

crykit build
crykit build --release
crykit build -f path/to/crykit.yml -o ./dist/my_app

Option	Default	Effect
-f FILE, --file FILE	./crykit.yml	Select the application configuration
-o FILE, --output FILE	bin/<app.name.underscore> beside the config	Choose the executable path
--release	Off	Enable Crystal release optimizations

Builds an executable without running it. Assets declared with app.assets = CryKit::Assets.directory("assets") are embedded and served through the same /assets/ URLs. See assets.

dist

crykit dist
crykit dist -f path/to/crykit.yml -o ./dist/MyApp.app
crykit dist --skip-release

Option	Default	Effect
-f FILE, --file FILE	./crykit.yml	Select the application configuration
-o FILE, --output FILE	dist/<app.name>.app beside the config	Choose the bundle path
--skip-release	Off	Disable the release optimizations enabled by default

Packages an ad hoc signed macOS application with embedded assets. Requires the targets/dist.cr recipe and macOS files generated by init. See Distribution for metadata, icons, plist customization, and signing scope.

Help and version

Invocation	Output
crykit --help, crykit -h	Available commands and global options
crykit <command> --help	Options for that command
crykit --version, crykit -v	CryKit v<version>, embedded in the executable

Help and version exit without reading app configuration or requiring build tools. Running crykit without arguments shows help.

CLI configuration

dev, build, and dist read ./crykit.yml, or the file selected with -f. Missing files and omitted fields use defaults.

Field	Default	Purpose
app.name	MyApp	Display name; its underscored form names the executable
app.entry	./src/main.cr	Crystal entry point
app.id	Unset	Application bundle identifier; required for dist
app.version	Nearest ancestor shard.yml version, or unset	Application version; required for dist
app.build_number	"1"	macOS bundle build number
app.icon	Unset	Square PNG or .icns file for dist
macos.min_system_version	"26.0"	Minimum macOS version for dist
development.watch	["./**/*.cr", "./**/*.ecr"]	Files, recursive directories, or globs watched by dev --watch

app:
  name: MyApp
  entry: ./src/main.cr
  id: com.example.my-app
development:
  watch:
    - ./src

Paths and version resolution

• Entry, icon, and watch paths resolve beside the selected configuration file.
• Compilation and application execution use the config directory as their working directory.
• Explicit build -o and dist -o paths resolve from the caller's directory.
• An explicit app.version takes precedence. Otherwise, the CLI runs shards version using the nearest ancestor manifest. A failed lookup for an existing shard reports an error; without a shard, the version stays unset.

From a CryKit source checkout, replace crykit with crystal run src/cli.cr --, for example:

crystal run src/cli.cr -- dev -f examples/demo/crykit.yml

Runtime environment

API or setting	Meaning
CryKit.env	Current environment; production by default
CryKit.env.dev?, CryKit.env.prod?	Check the active environment
crykit dev	Select development mode for the application
CRYKIT_ENV=dev crystal run src/main.cr	Select development mode without the CLI

Environment selection is separate from asset hotreload, source hotpatch, and source hotreload. Custom runners use the manual configuration.

Errors and exit status

Expected argument, configuration, filesystem, and tool failures print Error: <message> to standard error and exit with status 1. This includes distribution recipe loading and packaging. Unexpected internal exceptions retain their stack traces.

dev, build, and dist require the resolved entry to be a file. init, help, and version requests skip this check.