CLI Reference

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

ezkeel up

Deploy any repository to your server in one command. Auto-detects the framework, generates a Dockerfile if needed, builds the image, and deploys with zero-downtime.

Supported frameworks: Next.js, Vite, Express, Hono, Fastify, Remix, Nuxt, Astro, FastAPI, Django, Flask, Go, Rust, Rails, and static HTML. If a Dockerfile is present, it takes priority.

Database detection: Automatically detects PostgreSQL, MySQL, or SQLite via Prisma, Drizzle, package.json deps, Python deps, or .env.example DATABASE_URL.

Examples:

ezkeel server

Manage deployment servers. Add a VPS, list configured servers, or SSH into one.

server add

Register a new server for deployments. The server will be bootstrapped with Docker, Caddy, and the ezkeel agent.

Example:

server list

List all configured servers:

server ssh

SSH into a configured server:

ezkeel apps

List all deployed apps with their framework, status, and domain.

ezkeel logs

Show recent logs from a deployed app via the ezkeel agent.

ezkeel down

Stop and remove a deployed app, including its containers.

ezkeel env

Manage environment variables for deployed apps. Variables are stored in the app manifest and applied on the next ezkeel up.

env set

env list

ezkeel backup

Backup the PostgreSQL database for a deployed app. Runs pg_dump on the server via the ezkeel agent and saves the SQL dump locally.

Example:

ezkeel rollback

Roll back an app to its previous deployment. Before each deploy, the agent automatically tags the running image. Rollback swaps back to that previous image.

ezkeel doctor

Run diagnostic checks on your local machine and remote server. Checks: local Docker, SSH connectivity, remote Docker, agent version, DNS wildcard resolution, and disk space.

ezkeel domain

Manage custom domains for deployed apps. Add your own domain, and Caddy will auto-provision the SSL certificate. You need to point the domain to your server IP with a DNS A record.

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.

Example:

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.

Example:

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.

Example:

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.

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:

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.

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:

plan diff

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

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.

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.

environment start

Start the dev container (runs devcontainer up).

environment exec

Execute a command inside the running dev container.

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.

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

ezkeel ci status

Show recent CI workflow runs for a repository. Queries the Forgejo Actions API and prints a summary of the latest runs with their status.

Example:

ezkeel ci setup

Generate a CI workflow file for automating deploys or mirroring on push to main. Without flags, creates .forgejo/workflows/deploy.yaml for Forgejo Actions. With --github, creates .github/workflows/mirror.yaml for GitHub Actions instead.

ezkeel pages deploy

Deploy a static site to the EZKeel platform. Uses rsync over SSH to copy built files to the server, where Caddy serves them under the configured pages domain.

Example:

ezkeel deploy

Build a Docker image, push it to the Forgejo container registry, and deploy it to the production server via SSH. Reads the project name and registry URL from workspace.yaml.

Example:

ezkeel agent

Interact with AI agents. EZKeel includes 3 built-in agents (app-builder, code-reviewer, devops) and supports custom agents.

ezkeel agent list

List all available agents (built-in and custom).

ezkeel agent run <name> <prompt>

Execute a one-shot agent task. The agent runs the prompt and returns the result.

ezkeel agent chat <name>

Start an interactive WebSocket chat session with an agent. Type messages and get streaming responses.