CLI Commands

Complete reference for the easy-dev command-line interface.

Overview

easy-dev [command] [options]

Run easy-dev --help for a list of available commands.

Commands

start

Start the complete development environment.

easy-dev start [app-name] [options]

Arguments:

• app-name (optional): Override the app name from config

Options:

Option	Description
--skip-auth	Skip Kratos authentication step
--skip-install	Skip app installation via GraphQL
--no-browser	Don't open browser after start
-c, --config <path>	Path to devkit.config.ts
-v, --verbose	Enable verbose output

What it does:

1. Loads configuration from devkit.config.ts
2. Checks Docker infrastructure health (AppServer, Kratos, OpenFGA)
3. Authenticates with Kratos (unless --skip-auth)
4. Starts the backend process
5. Waits for backend health check
6. Installs app via GraphQL (unless --skip-install)
7. Starts Vite frontend dev server
8. Restarts shell container with dev mode configuration
9. Opens browser (unless --no-browser)

Example:

# Start with default config
easy-dev start

# Start with verbose output
easy-dev start -v

# Skip authentication (use existing session)
easy-dev start --skip-auth

# Use custom config file
easy-dev start -c ./config/dev.config.ts

---

stop

Stop all managed processes.

easy-dev stop

Sends SIGTERM to all managed processes (backend, frontend). The shell container continues running in Docker.

Example:

easy-dev stop

---

status

Show status of all services.

easy-dev status [options]

Options:

Option	Description
-c, --config <path>	Path to devkit.config.ts

Output includes:

• Managed processes (backend, frontend) with PIDs and ports
• Docker infrastructure services health status

Example:

easy-dev status

# Output:
# Managed Processes:
#   Backend:  Running (PID: 12345, Port: 1338)
#   Frontend: Running (PID: 12346, Port: 5173)
#
# Infrastructure:
#   AppServer: ✓ Healthy
#   Kratos:    ✓ Healthy
#   OpenFGA:   ✓ Healthy

---

auth

Authenticate with Kratos and grant OpenFGA permissions.

easy-dev auth [options]

Options:

Option	Description
-c, --config <path>	Path to devkit.config.ts
-v, --verbose	Enable verbose output

Output:

• User ID from Kratos
• Session token
• OpenFGA permission grants

Example:

easy-dev auth -v

# Output:
# Authenticating with Kratos...
# User ID: 93c72577-f4c6-43e9-95fe-74679198a633
# Session token: ory_st_...
# Granting OpenFGA permissions...
# ✓ Authentication complete

---

install

Install an app via GraphQL API.

easy-dev install <app-name> [options]

Arguments:

• app-name (required): The app identifier to install

Options:

Option	Description
-c, --config <path>	Path to devkit.config.ts
-v, --verbose	Enable verbose output

Example:

easy-dev install de.easy-m.statistics

---

uninstall

Uninstall an app via GraphQL API.

easy-dev uninstall <app-name> [options]

Arguments:

• app-name (required): The app identifier to uninstall

Options:

Option	Description
-c, --config <path>	Path to devkit.config.ts
-v, --verbose	Enable verbose output

Example:

easy-dev uninstall de.easy-m.statistics

---

logs

View logs for a specific service.

easy-dev logs [service]

Arguments:

• service (optional): backend, frontend, or shell

Note: During easy-dev start, logs are streamed directly to the console.

---

Global Options

These options are available for all commands:

Option	Description
-V, --version	Output version number
-h, --help	Display help for command

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Infrastructure not available

Keyboard Shortcuts

During easy-dev start:

Key	Action
Ctrl+C	Graceful shutdown (SIGTERM)
Ctrl+C (twice)	Force shutdown (SIGKILL)

Common Workflows

Daily Development

# Start everything
easy-dev start

# ... develop with HMR ...

# Stop when done
easy-dev stop

Quick Restart

# Stop and start
easy-dev stop && easy-dev start

Skip Authentication

If you already have a valid session:

easy-dev start --skip-auth

Debug Mode

easy-dev start -v

Troubleshooting

Infrastructure Not Available

Error: AppServer not available at http://localhost:8080

Solution: Start Docker infrastructure first:

cd docker
./scripts/start-local.sh

Authentication Failed

Error: Kratos authentication failed

Solution: Check Kratos is running and credentials are correct:

curl http://localhost:4433/health/ready

Port Already in Use

Error: Port 5173 is already in use

Solution: Stop the existing process or use a different port in config.

Next Steps

• Vite Plugin - Configure the Vite plugin
• App Setup - Complete app setup guide