Skip to content

CLI commands

The ghuri binary comes from @ghuri/cli, which new projects list as a dev dependency. Run it from anywhere inside the project with npx ghuri (or npm run ghuri -- <command>).

Terminal window
npx ghuri <command> [arguments] [options]
npx ghuri help # list every command, grouped by where it comes from
npx ghuri help <command> # arguments and options for one command
npx ghuri <command> --help # the same
npx ghuri --version # the CLI version
  1. It walks up from the current directory to the nearest package.json with a ghuri key or a src/settings.ts. The settings module is package.json#ghuri.settings (default src/settings.ts), or --settings <path>.

  2. It loads TypeScript with jiti, so there is no build step.

  3. It builds env, from highest to lowest precedence:

    • Worker bindings (D1, R2, KV, Hyperdrive, …) from wrangler.jsonc / wrangler.json / wrangler.toml through Wrangler’s getPlatformProxy(): local by default (Miniflare, state in .wrangler/state, shared with wrangler dev), remote with --remote;
    • process.env;
    • .dev.vars (or .dev.vars.<env> with --env), then .env, .env.local, .env.<env>;
    • wrangler vars.

    Without a wrangler config (or without wrangler installed) env is process.env plus the files above.

  4. It runs createApp(settings).setup(env), which populates INSTALLED_APPS and registers app commands, runs the command, then closes database connections and the bindings proxy.

Commands come from three places, and ghuri help groups them that way: the CLI itself ([ghuri]), @ghuri/orm ([orm]), and the commands of each installed app (for example createsuperuser from @ghuri/auth). An app command can override a built-in one (except help). See Management commands to write your own.

Every command accepts these.

Option Meaning
--settings <path> Settings module (default package.json#ghuri.settings or src/settings.ts).
--env <name> Wrangler environment (env.<name> in the wrangler config) for bindings and vars.
--remote Use remote D1, R2 and KV bindings instead of the local simulator.
--persist-to <dir> Local binding state directory (default .wrangler/state).
--traceback Print full stack traces on errors.
--no-color Plain output (NO_COLOR is honoured too).
-h, --help Show help for the command.

--remote uses Wrangler 4’s per-binding remote mode: the CLI writes a temporary copy of your wrangler config with every D1, R2 and KV binding marked "remote": true, calls getPlatformProxy({ remoteBindings: true }), and deletes the copy afterwards. You need wrangler login and real resource ids (such as database_id) in the config.


Terminal window
npx ghuri startproject <name> [directory] [--db d1|postgres|sqlite] [--pm npm|pnpm|bun|yarn] [--graphql] [--no-install]

Creates a new project. It works outside a project; npm create ghuri@latest runs it for you. It generates a random SECRET_KEY into .dev.vars.

Argument / option Default Meaning
name required Project name; used for the directory, package.json and Worker name.
directory ./<name> Where to create it (must be empty or missing).
--db d1 d1: Cloudflare D1 + R2. postgres: Hyperdrive on Workers, DATABASE_URL elsewhere. sqlite: a Node project with better-sqlite3 and file storage, no wrangler.
--pm the one running the command, else npm Package manager for install and the printed next steps.
--graphql off Add GraphQL: @ghuri/graphql and graphql dependencies, GraphQLConfig in INSTALLED_APPS, src/schema.ts as GRAPHQL.SCHEMA and GraphQLView at /graphql/.
--no-install Do not install dependencies.
Terminal window
npx ghuri startapp <name> [directory] [--no-register]

Creates src/<name>/ with app.ts, models.ts, views.ts, urls.ts, serializers.ts, schema.ts (a commented GraphQL example), admin.ts, tests.ts and migrations/index.ts, and adds the generated AppConfig (<Name>Config) to INSTALLED_APPS in your settings (an import plus a list entry) when the settings file has the usual shape. It prints the path(...) line to add to src/urls.ts.

Argument / option Meaning
name Lowercase identifier (blog, blog_posts). Names of Ghuri packages (auth, admin, …) are reserved.
directory Destination (default src/<name>).
--no-register Do not edit INSTALLED_APPS.
Terminal window
npx ghuri runserver [addrport] [-p <port>] [--host <host>] [--node] [--remote] [-- wrangler args]

Starts the development server. In a project with a wrangler config it runs wrangler dev (port 8787); extra arguments are passed to Wrangler. With --node, or when there is no wrangler config, it serves the app in-process with @ghuri/core/node (port 8000), still using local Wrangler bindings when they exist.

Argument / option Default Meaning
addrport A port (8000) or ipaddr:port.
-p, --port 8787 (wrangler) / 8000 (Node) Port to listen on.
--host localhost Interface to bind.
--node off Serve with Node instead of wrangler dev.
--remote off wrangler dev --remote; with --node, use remote D1, R2 and KV.
Terminal window
npx ghuri shell [-c <code>]

A Node REPL with the project loaded: apps, settings, env, core, orm, getModel() and every installed model by class name (Post, User, …). Top-level await works. -c, --command <code> (or code piped on stdin) evaluates it, prints the result and exits:

Terminal window
npx ghuri shell -c "await Post.objects.count()"
Terminal window
npx ghuri check [--deploy] [-t <tag>] [--fail-level <level>] [--list-tags]

Runs system checks (runChecks() from @ghuri/core: settings validation and anything registered with checks.register()). The same checks run at startup when DEBUG is on.

Option Meaning
--deploy Also run checks relevant to a production deployment.
-t, --tag <tag> Only checks with this tag. Repeatable.
--fail-level <level> CRITICAL, ERROR (default), WARNING, INFO or DEBUG: the level that makes the command exit non-zero.
--list-tags List the available tags.
Terminal window
npx ghuri test [--watch] [vitest arguments]

Runs vitest run in the project (--watch for watch mode). Other arguments go to vitest, for example npx ghuri test src/blog. See Testing.

Terminal window
npx ghuri eval [--models <list>] [--repeat <n>] [--case <text>] [--report <dir>] [vitest arguments]

Runs the agent eval suites (src/**/evals.ts, src/**/*.eval.ts, evals/**/*.eval.ts) with vitest, one file at a time, using the project’s vitest config. ghuri test does not run these files. --models compares the given models instead of the suites’ own (comma separated), --repeat runs each case several times, --case keeps only cases whose name contains the text and --report also writes one JSON report per suite. Evals call real models unless the suites use mocks, so they cost money. See Evaluating agents.

Terminal window
npx ghuri deploy [--migrate] [--skip-migrations] [--dry-run] [--no-input] [-- wrangler args]

Optionally applies migrations to the remote database (ghuri migrate --remote), then runs wrangler deploy. Without --migrate or --skip-migrations it asks; with --no-input (or without a terminal) it skips migrations and says so. Extra arguments go to Wrangler. See Deploying to Cloudflare Workers.

Option Meaning
--migrate Apply remote migrations first without asking. A failed migration aborts the deploy.
--skip-migrations Do not apply migrations (and do not ask).
--dry-run wrangler deploy --dry-run; skips migrations.
--no-input Never prompt; migrations run only with --migrate.
Terminal window
npx ghuri routes [--format table|json]

Lists URL patterns with their names, methods and views (django-extensions’ show_urls; show_urls is an alias).

Terminal window
npx ghuri diffsettings [--all] [--show-secrets]

Shows settings that differ from Ghuri’s defaults. --all lists every setting, marking non-defaults with ###. Secret-looking values are masked unless --show-secrets is given.

Terminal window
npx ghuri version [--short]
npx ghuri help [command]

version prints the CLI version plus the project’s @ghuri/*, hono, wrangler and Node versions (--short prints only the CLI version).

Terminal window
npx ghuri mcp [--docs-url <url-or-file>]

Runs a Model Context Protocol server over stdio for AI coding agents (Claude Code, Codex, Cursor, VS Code and other MCP clients). Configure the client to run npx ghuri mcp in the project directory, for example:

Terminal window
claude mcp add ghuri -- npx ghuri mcp

or commit a .mcp.json (Claude Code; Cursor reads the same shape from .cursor/mcp.json):

{ "mcpServers": { "ghuri": { "command": "npx", "args": ["ghuri", "mcp"] } } }
# Codex: ~/.codex/config.toml or .codex/config.toml
[mcp_servers.ghuri]
command = "npx"
args = ["ghuri", "mcp"]

VS Code uses .vscode/mcp.json with a servers key: { "servers": { "ghuri": { "type": "stdio", "command": "npx", "args": ["ghuri", "mcp"] } } }.

Tool What it does
project_info Settings module, runtime, bindings, DEBUG, INSTALLED_APPS, DATABASES, STORAGES, CACHES, MIDDLEWARE, other settings (secrets hidden), package versions
list_apps Installed apps with their models, commands and migrations
list_models / describe_model Models, fields and options, relations, reverse relations, Meta and managers
list_routes URL patterns, like routes
openapi_schema The REST API as OpenAPI 3.1, like generateschema: one line per operation by default; with path (a prefix such as /api/posts/) or tag, or summary: false, the JSON of those operations and the components they reference
list_commands Every command, like help
show_migrations Applied and unapplied migrations on the local database
run_command Runs a command (check, makemigrations, migrate, test, startapp, app commands, …) and returns the exit code and output
search_docs / get_doc Searches and reads this documentation (llms-full.txt)

The project is reloaded in a child process whenever a source file changed, so the agent sees its own edits, and a project that fails to load returns the error to the agent instead of stopping the server. Only protocol messages are written to stdout. run_command refuses runserver, shell, dbshell, deploy, flush, startproject, mcp, createsuperuser without --no-input, test --watch and --remote, so an agent never touches production bindings. --docs-url (or GHURI_DOCS_URL) reads the docs from another URL or a local file.


These come from @ghuri/orm/commands and are available when the project has @ghuri/orm installed. Every command that touches a database takes --database <alias> (a key of DATABASES, default default), and --remote to use remote D1.

Terminal window
npx ghuri makemigrations [app_label ...] [-n <name>] [--empty] [--dry-run] [--check] [--merge] [--no-input]

Compares your models with the state recorded in existing migrations, writes new migration files to src/<app>/migrations/, and regenerates migrations/index.ts. It asks whether a model or field was renamed, and for a one-off default when you add a NOT NULL field without a default.

Argument / option Meaning
app_label Limit to these apps. Default: all installed apps with a path.
-n, --name Name for the migration file (0003_<name>.ts).
--empty Create an empty migration to fill with RunSQL / RunCode.
--dry-run Show what would be written without writing.
--check Exit non-zero if model changes are missing migrations (for CI).
--merge Create a merge migration when two branches added migrations to the same app.
--no-input Do not prompt: renames are treated as remove + add, and a missing one-off default is an error.
Terminal window
npx ghuri migrate [app_label] [migration_name] [--fake] [--fake-initial] [--plan] [--run-syncdb] [--no-input] [--database <alias>]

Applies (or unapplies) migrations and records them in the ghuri_migrations table. Each migration runs atomically with its record: in a transaction on SQLite and Postgres, as one batch() on D1.

Argument / option Meaning
app_label Only migrate this app.
migration_name Migrate the app to this migration, unapplying later ones. zero unapplies all.
--fake Mark migrations as applied (or unapplied) without running them.
--fake-initial Fake initial migrations whose tables already exist.
--plan Show the operations that would run, without running them.
--run-syncdb Create tables for apps without migrations.
--no-input Do not prompt.
--database <alias> Database to migrate.
Terminal window
npx ghuri showmigrations [app_label ...] [-p] [--database <alias>]

Lists migrations per app with [X] for applied and [ ] for pending. -p, --plan shows all migrations in the order they would be applied.

Terminal window
npx ghuri sqlmigrate <app_label> <migration_name> [--backwards] [--dialect sqlite|postgresql] [--database <alias>]
npx ghuri sqlmigrate --all [--dialect sqlite] [--out migrations-sql]

Prints the SQL a migration would run. Without --dialect it uses the dialect of the selected database.

Option Meaning
--backwards The SQL to unapply the migration.
--dialect sqlite (SQLite and D1) or postgresql.
--all Every migration of every app, as numbered SQL files in dependency order (for wrangler d1 migrations apply). Each file also inserts its ghuri_migrations row, so showmigrations agrees with Wrangler. Re-running only adds files for new migrations.
--out <dir> With --all: directory to write the .sql files to.
Terminal window
npx ghuri dumpdata [app_label[.Model] ...] [-e <label>] [--indent <n>] [-o <file>] [--database <alias>]

Writes rows as JSON fixtures to stdout (or --output). The format matches Django’s:

[{ "model": "blog.post", "pk": 1, "fields": { "title": "Hello", "author": 1, "tags": [2, 3] } }]
Argument / option Meaning
app_label[.Model] Only these apps or models (blog, blog.Post). Default: everything.
-e, --exclude Skip an app or model. Repeatable.
--indent Pretty-print with this many spaces.
-o, --output Write to a file instead of stdout.
--format Only json.
--database <alias> Read from this database.
Terminal window
npx ghuri loaddata <fixture ...> [-e <label>] [--database <alias>]

Loads fixtures produced by dumpdata: file paths, names found in <app>/fixtures/, or - for stdin. Objects are upserted by primary key in dependency order inside one transaction (one batch on D1), many-to-many rows are replaced, and Postgres sequences are reset afterwards.

Argument / option Meaning
fixture One or more fixtures.
-e, --exclude Skip an app or model. Repeatable.
--database <alias> Write to this database.
Terminal window
npx ghuri copydata --from <alias> --to <alias> [app_label ...] [-e <label>] [--flush] [--no-input]

Copies every row from one database alias to another in one process (a dumpdata plus loaddata without the intermediate file). Migrate the destination first.

Argument / option Meaning
--from Source alias (default default).
--to Destination alias.
app_label Only these apps or models.
-e, --exclude Skip an app or model. Repeatable.
--flush Delete every row of the destination first (asks for confirmation).
--no-input Do not prompt.
src/settings.ts
DATABASES: {
default: d1('DB'),
pg: postgres({ url: env.DATABASE_URL }),
},
Terminal window
npx ghuri migrate --database pg
npx ghuri copydata --from default --to pg
# or, with a file in between:
npx ghuri dumpdata --database default -o data.json && npx ghuri loaddata data.json --database pg

See Migrating from D1 to Postgres.

Terminal window
npx ghuri flush [--no-input] [--database <alias>]

Deletes every row from every table, keeping the schema and the migration history. Asks for confirmation unless --no-input is given.


These come from the apps in @ghuri/auth and are available when the app is installed.

Terminal window
npx ghuri createsuperuser [--username <name>] [--email <email>] [--password <pw>] [--no-input] [--database <alias>]

Creates a user with isStaff and isSuperuser set, prompting for the username, the email and the password (twice). There is one option per USERNAME_FIELD and REQUIRED_FIELDS entry of your user model. With --no-input, values come from the options or from GHURI_SUPERUSER_<FIELD> environment variables, and the password from --password or (preferably) GHURI_SUPERUSER_PASSWORD.

Terminal window
npx ghuri changepassword [username] [--password <pw>] [--database <alias>]

Sets a user’s password, prompting twice. Defaults to the user named after your OS login ($USER).

Terminal window
npx ghuri clearsessions

Deletes expired sessions from the database. Run it by hand or from a scheduled task.

Terminal window
npx ghuri drf_create_token <username> [-r]

Creates (or prints) the API token for a user. -r, --reset replaces an existing token.

Terminal window
npx ghuri flushexpiredtokens

Deletes expired JWT refresh tokens from the outstanding-token list.

Terminal window
npx ghuri generateschema [--file <path>] [--format openapi|openapi-json] [--title <title>]
[--description <text>] [--api-version <version>] [--url <url>] [--indent <n>]

Writes the OpenAPI 3.1 schema of the REST API (DRF’s generateschema). Add RestFrameworkConfig from @ghuri/rest to INSTALLED_APPS to get it; startproject does. It documents ROOT_URLCONF, using the options of the first SchemaView routed there (title, version, description, servers, patterns, prefix), so the output matches what that view serves.

Option Meaning
--file <path> Write to this file instead of stdout.
--format <format> openapi (YAML, the default) or openapi-json. A --file ending in .json defaults to JSON.
--title <title> info.title.
--description <text> info.description.
--api-version <version> info.version (DRF’s --api_version).
--url <url> Base URL of the API, written as servers: [{ url }].
--indent <n> Indentation of the JSON output (default 2).

See OpenAPI.


Terminal window
npx ghuri graphql_schema [-o, --out <file>] [--json] [--sort] [--indent <n>]

Prints the schema of GRAPHQL.SCHEMA (graphene-django’s graphql_schema). Add GraphQLConfig from @ghuri/graphql to INSTALLED_APPS to get it.

Option Meaning
-o, --out <file> Write to this file instead of stdout.
--json Output the introspection result as JSON (for client code generators) instead of SDL.
--sort Sort types and fields alphabetically.
--indent <n> Indentation of the JSON output (default 2).

See GraphQL.


0 on success, 1 on a CommandError or failed check (or the CommandError’s own return code), 2 on a usage error (unknown option, missing argument), and whatever number a command’s handle() returns otherwise.