CLI Reference

Complete reference for every ezkeel command, with usage, flags, and examples.

ezkeel init

Initialize a new EZKeel project. Scaffolds the directory structure, creates a workspace.yaml, sets up Dev Container and AI persona configuration, and optionally creates a Forgejo repository.

usage

ezkeel init <project-name> [flags]

Flag	Default	Description
`--forgejo-url`	none	Forgejo instance URL (e.g. `https://git.ezkeel.com`)
`--forgejo-token`	none	Forgejo API token for creating the repository
`--infisical-url`	none	Infisical instance URL (e.g. `https://secrets.ezkeel.com`)
`--infisical-token`	none	Infisical API token for creating the project
`--infisical-org`	none	Infisical organization ID to create the project in

Example:

terminal

$ ezkeel init my-saas \ --forgejo-url https://git.example.com \ --forgejo-token $FORGEJO_TOKEN Created repository: https://git.example.com/org/my-saas.git created workspace.yaml created CLAUDE.md created AGENTS.md created .devcontainer/devcontainer.json created .github/workflows/ci.yaml created .gitignore Project "my-saas" initialized at /home/dev/my-saas

ezkeel clone

Clone an EZKeel project and set it up locally. Clones the Git repo, injects secrets for the specified environment, and scaffolds the AI config.

usage

ezkeel clone <project-name> [flags]

Flag	Default	Description
`--forgejo-url`	none	Forgejo instance base URL (e.g. `https://git.ezkeel.com/myorg`)
`--env`	`dev`	Environment to inject secrets for

Example:

terminal

$ ezkeel clone my-saas --forgejo-url https://git.example.com/org Cloning https://git.example.com/org/my-saas... Secrets injected for environment "dev" Project "my-saas" cloned and configured.

ezkeel secrets inject

Export secrets for the given environment as shell export statements. Reads the Infisical project from workspace.yaml and outputs key-value pairs to stdout.

usage

ezkeel secrets inject <environment>

Example:

terminal

# Print export statements $ ezkeel secrets inject dev export ANTHROPIC_API_KEY="sk-ant-..." export DATABASE_URL="postgres://..." # Load them into your current shell $ eval $(ezkeel secrets inject dev)

ezkeel ai

Run an AI tool with automatically injected secrets. Resolves model names from workspace.yaml, injects the required API key from Infisical, and launches the tool with your prompt.

usage

ezkeel ai <tool> <prompt...> [flags]

Flag	Default	Description
`--env`	`dev`	Environment to inject secrets for

The <tool> argument maps to known AI tools:

claude — Claude Code (requires ANTHROPIC_API_KEY)
codex — OpenAI Codex (requires OPENAI_API_KEY)
local — resolves to the ai.models.local value in workspace.yaml (e.g. ollama/llama3)

Examples:

terminal

$ ezkeel ai claude "refactor the auth module" $ ezkeel ai codex "write tests for the API layer" $ ezkeel ai local "explain this function"

ezkeel sync push / pull

Synchronize the AI persona configuration (.claude/ directory) between your local machine and a dedicated ezkeel/persona Git branch. This keeps your AI configuration portable across machines.

usage

ezkeel sync push # push .claude/ to origin/ezkeel/persona ezkeel sync pull # pull .claude/ from origin/ezkeel/persona

Push stashes your current work, checks out the ezkeel/persona branch, commits the .claude/ directory, force-pushes, then returns you to your previous branch.

Pull fetches the remote branch and checks out just the .claude/ subtree into your working directory.

ezkeel plan new / diff

Manage project planning documents in the plans/ directory.

plan new

Create a new dated plan document and open it in $EDITOR:

terminal

$ ezkeel plan new auth-redesign Created plans/2025-01-15-auth-redesign.md

plan diff

Show the diff of plan changes since the last Git tag:

terminal

$ ezkeel plan diff Plans changed since v0.2.0: + ## New: auth redesign proposal ~ Updated success criteria for API plan

ezkeel publish

Publish public paths to a separate open-source repository. Reads the visibility rules from workspace.yaml, copies only public paths to a temp directory, and force-pushes to the public repo.

usage

ezkeel publish [flags]

Flag	Default	Description
`--forgejo-url`	none	Public repository URL to push to
`--dry-run`	`false`	List files that would be published without pushing
`--diff`	`false`	Show configured public/private paths

Examples:

terminal

# Preview what would be published $ ezkeel publish --dry-run Dry run -- files that would be published: src/main.go docs/README.md LICENSE # Actually publish $ ezkeel publish --forgejo-url https://git.example.com/org/my-saas-public Published public paths to https://git.example.com/org/my-saas-public

ezkeel platform install

Install the full EZKeel platform (Forgejo, Infisical, PostgreSQL, Redis, Caddy, Runner) on a server using Docker Compose. Generates secrets, writes config files, and starts all services.

usage

ezkeel platform install [flags]

Flag	Default	Description
`--dir`	`/opt/ezkeel`	Directory to install the platform into
`--forgejo-domain`	`git.ezkeel.com`	Domain for the Forgejo instance
`--infisical-domain`	`secrets.ezkeel.com`	Domain for the Infisical instance

See Installation and Platform Setup for detailed deployment instructions.

ezkeel environment

Manage the project's dev container. Build the container image, start it, or execute commands inside it. Aliased as ezkeel env.

environment build

Build the dev container image defined in .devcontainer/devcontainer.json.

terminal

$ ezkeel environment build Building dev container for /home/dev/my-saas...

environment start

Start the dev container (runs devcontainer up).

terminal

$ ezkeel environment start Starting dev container for /home/dev/my-saas...

environment exec

Execute a command inside the running dev container.

terminal

$ ezkeel env exec -- go test ./...

Flag	Default	Description
`--dir`	current directory	Project directory containing `.devcontainer/`

Prerequisite: Requires the Dev Containers CLI. Install with npm install -g @devcontainers/cli.

ezkeel platform setup

Print a step-by-step guide for creating admin accounts after ezkeel platform install. Reads credentials from the platform's .env file.

usage

ezkeel platform setup [flags]

Flag	Default	Description
`--dir`	`/opt/ezkeel`	Platform install directory containing `.env`

This guide is also printed automatically at the end of ezkeel platform install.