EN CLI Reference

Forge CLI: commands and behavior

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

The package exposes equivalent forge and json-api-forge entry points. A source checkout also supports python forge.py. Put the global --root option before the subcommand:

forge --root /srv/forge validate

Commands

Command	Options	Effect
new NAME / new-app NAME	--slug, --preset	Create app/NAME; reject an existing target
init	--production, --editor, --force	Generate .env and random secrets
validate	—	Validate project models and semantics
doctor	--production, --json	Diagnose security, routing and deployment
routes	—	Print HTTP and WebSocket routes
openapi	--output / -o	Export generated OpenAPI
schema	—	Regenerate JSON schemas from models
migrate	—	Create support tables and declarative auto-create resources
secrets	--count	Generate strong secrets to stdout without editing files
dev	--host, --port, --reload, --no-reload, --log-level	Run the development ASGI server

Both the root command and subcommands support --help. doctor exits with code 2 when it finds error-level diagnostics. --json is suitable for CI and machine-readable reporting.

Presets

Preset	Initial contents
minimal	Database, bootstrap, performance settings and empty resources
postgres-api	The above plus an items SQL resource
discord-bot	Items and a bot role
game-backend	Items and the gaming feature pack

Preset names do not mean a complete product has been installed. postgres-api does not install PostgreSQL, and discord-bot does not launch a Discord bot.

init and an existing .env

For a new file, --production sets APP_ENV=production and generates OPERATOR_TOKEN; --editor generates the management setup secret and enablement setting. Project JSON environment references without defaults whose names contain SECRET/TOKEN/KEY/PASSWORD are also treated as managed secrets.

• forge init refuses to overwrite an existing file.
• forge init --force rotates all discovered managed secrets, rather than only filling the new project's missing key.
• Other lines are preserved. On an existing .env, --production or --editor therefore does not rewrite every operating-mode setting; inspect APP_ENV and EDITOR_API_ENABLED separately.

To add just one secret, generate it with forge secrets and add the corresponding variable to your secret management. Keep real values out of logs, issues and the Wiki.

The scope of migrate

forge migrate is not a versioned business-data migration system. It does not build an Alembic history, redesign existing columns, migrate arbitrary data or create rollback plans. Follow the database migration guide for production changes.

The scope of dev

Defaults are host 127.0.0.1, port 8000 and Python reload enabled. --no-reload disables the Python reloader; disable the JSON watcher separately with APPS_AUTO_RELOAD=false. Global proxy rewriting is disabled so Forge can apply its own proxy-trust policies.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/framework/cli.py
• main/pyproject.toml

---

English home · All English pages · Version maintenance