---
title: CLI Reference
description: Complete reference for all XBP CLI commands
---
Complete reference for all XBP commands, options, and flags.
Available for all commands:
Enable debug mode with verbose output.
```bash
xbp --debug diag
```
List PM2 processes (shorthand).
```bash
xbp -l
```
Filter by port number (for ports command).
```bash
xbp -p 3000
```
System diagnostics and health checks.
```bash
xbp diag [--nginx] [--ports <PORTS>] [--no-speed-test]
```
**Options:**
- `--nginx` - Check only Nginx
- `--ports <PORTS>` - Check specific ports (comma-separated)
- `--no-speed-test` - Skip internet speed test
[Full Documentation](/docs/commands/diag)
Run single health check.
```bash
xbp monitor check
```
Start monitoring daemon.
```bash
xbp monitor start
```
Create or update a cert-manager Let's Encrypt issuer.
```bash
xbp kubernetes issuer --email floris@xylex.group [--namespace default] [--context <CTX>] [--dry-run]
```
#### `xbp kubernetes addons`
List, enable, or disable MicroK8s addons.
```bash
xbp kubernetes addons list
xbp kubernetes addons enable cert-manager
xbp kubernetes addons disable ingress
```
#### `xbp kubernetes observability-creds`
Print decoded Grafana admin credentials from the observability secret.
```bash
xbp kubernetes observability-creds
```
[Full Documentation](/docs/commands/monitor)
### Logging
#### `xbp tail`
Tail log files.
```bash
xbp tail [--kafka] [--ship]
```
**Options:**
- `--kafka` - Tail from Kafka topic
- `--ship` - Ship logs to Kafka
[Full Documentation](/docs/commands/tail)
### Port Management
#### `xbp ports`
List and manage network ports.
```bash
xbp ports [-p <PORT>] [--kill] [-n] [--no-local] [--exposure]
```
**Options:**
- `-p, --port <PORT>` - Filter by port
- `--kill` - Kill processes on port
- `-n, --nginx` - Show only Nginx ports
- `--no-local` - Exclude connections where LocalAddr equals RemoteAddr
- `--exposure` - Show bind/firewall exposure diagnostics for the selected ports
[Full Documentation](/docs/commands/ports)
### Service Management
#### `xbp services`
List all services.
```bash
xbp services
```
#### `xbp service <COMMAND> <NAME>`
Run service command.
```bash
xbp service build api
xbp service install frontend
xbp service start worker
xbp service dev api
```
**Commands:**
- `build` - Build the service
- `install` - Install dependencies
- `start` - Start the service
- `dev` - Run in development mode
- `stop` - Stop the service
### Deployment
#### `xbp redeploy [SERVICE]`
Redeploy services.
```bash
xbp redeploy # All services
xbp redeploy api # Specific service
```
#### `xbp redeploy-v2`
Remote deployment.
```bash
xbp redeploy-v2 -u <USER> -h <HOST> -d <DIR> [-p <PASSWORD>]
```
**Options:**
- `-u, --username <USER>` - SSH username
- `-h, --host <HOST>` - SSH host
- `-d, --project-dir <DIR>` - Project directory
- `-p, --password <PASSWORD>` - SSH password (optional)
### Nginx Management
#### `xbp nginx setup`
Provision Nginx HTTPS reverse proxy and certificates.
```bash
xbp nginx setup --domain <DOMAIN> --port <PORT> --email <EMAIL>
```
**Options:**
- `-d, --domain <DOMAIN>` - Domain name (supports wildcard like `*.example.com`)
- `-p, --port <PORT>` - Port to proxy to
- `-e, --email <EMAIL>` - Let's Encrypt registration email
- `--dns-mode <manual|plugin>` - DNS mode for wildcard domains (default: `manual`)
- `--dns-plugin <NAME>` - DNS provider plugin for plugin mode (example: `cloudflare`)
- `--dns-creds <PATH>` - DNS plugin credentials file path
- `--include-base <true|false>` - Include base domain when issuing wildcard certs (default: `true`)
Examples:
```bash
xbp nginx setup --domain api.example.com --port 3000 --email ops@example.com
xbp nginx setup --domain '*.example.com' --port 3000 --email ops@example.com --dns-mode manual
xbp nginx setup --domain '*.example.com' --port 3000 --email ops@example.com --dns-mode plugin --dns-plugin cloudflare --dns-creds /root/.secrets/certbot/cloudflare.ini
```
List Nginx configurations.
```bash
xbp nginx list
```
Update Nginx configuration.
```bash
xbp nginx update --domain <DOMAIN> --port <PORT>
```
Show one or all detected Nginx site configs.
```bash
xbp nginx show
xbp nginx show api.example.com
```
Add a persistent floating IP on the detected Linux network backend.
```bash
xbp network floating-ip add --ip <IP> [--cidr <N>] [--interface <IFACE>] [--label <NAME>] [--apply] [--dry-run]
```
Examples:
```bash
xbp network floating-ip add --ip 203.0.113.10
xbp network floating-ip add --ip 2a01:4f9:0:2a1::2 --cidr 64 --interface eth0 --apply
```
List floating IP entries discovered from runtime and persistent config.
```bash
xbp network floating-ip list
xbp network floating-ip list --json
```
List discovered network config files and backend detection result.
```bash
xbp network config list
xbp network config list --json
```
List PM2 processes.
```bash
xbp list
```
View service logs. With the `docker` feature enabled, `PROJECT` may be a Docker container name or ID prefix; matching containers stream via `docker logs -f` (sudo fallback). Otherwise PM2 logs are shown.
```bash
xbp logs xbp logs api ```
**Options:**
- `--ssh-host <HOST>` - SSH host to stream remote logs from.
- `--ssh-username <USER>` - SSH username for the remote server.
- `--ssh-password <PASSWORD>` - SSH password for the remote server.
View configuration.
```bash
xbp config
```
Provider key management:
```bash
xbp config openrouter set-key [KEY]
xbp config openrouter show [--raw]
xbp config openrouter delete-key
xbp config github set-key [TOKEN]
xbp config github show [--raw]
xbp config github delete-key
```
Initial setup.
```bash
xbp setup
```
Make HTTP request.
```bash
xbp curl https://api.example.com/health
```
Feature-gated pass-through wrapper around the Docker CLI. With no args it shows Docker help; otherwise arguments are forwarded verbatim.
```bash
xbp docker ps
xbp docker compose ls
xbp docker run -it ubuntu bash
```
Install package.
```bash
xbp install docker
xbp install nginx
xbp install grafana
```
Create and push a version tag, then publish a GitHub release.
```bash
xbp version release
xbp version release --version 10.16.0
xbp version release --notes-file RELEASE_NOTES.md
xbp version release --allow-dirty
```
Generate systemd service units from the current `.xbp/xbp.yaml`.
```bash
xbp generate systemd [--service <SERVICE>] [--output-dir /etc/systemd/system] [--api/--no-api]
```
**Options:**
- `--service <SERVICE>` - Only emit the unit for a single service name.
- `--output-dir <DIR>` - Write units to a custom directory (default `/etc/systemd/system`).
- `--api/--no-api` - Also generate the `xbp-api.service` unit that runs the built-in API (default: on).
> Running this command on Linux usually requires root privileges when targeting `/etc/systemd/system`. Review the generated files before enabling them with `systemctl daemon-reload` and `systemctl enable`.
```bash
xbp diag && xbp service build api && xbp service start api
```
```bash
xbp monitor check || echo "Health check failed"
```
```bash
xbp monitor start &
xbp tail --ship &
```
Start XBP in API mode.
```bash
export PORT_XBP_API=8080
xbp
```
Set logging level.
```bash
export RUST_LOG=debug
xbp diag
```
Enable debug mode.
```bash
export XBP_DEBUG=1
xbp services
```
- `0` - Success
- `1` - General error
- `2` - Configuration error
- `3` - Network error
- `4` - Service error
```
[component] message
```
```
[component] Success message
```
```
[component] Warning message
```
```
[component] Error message
```
```bash
xbp diag > diagnostics.txt
```
```bash
xbp monitor check >> health-checks.log
```
```bash
xbp tail | grep ERROR
```
```bash
xbp ports | wc -l
```
```bash
if xbp monitor check; then
echo "Service is healthy"
exit 0
else
echo "Service is down"
xbp service start api
exit 1
fi
```
```python
import subprocess
import sys
result = subprocess.run(['xbp', 'monitor', 'check'],
capture_output=True)
if result.returncode == 0:
print("Health check passed")
else:
print("Health check failed")
sys.exit(1)
```
```javascript
const { exec } = require('child_process');
exec('xbp monitor check', (error, stdout, stderr) => {
if (error) {
console.error('Health check failed');
process.exit(1);
}
console.log('Health check passed');
});
```
Create shortcuts for common commands:
```bash
alias xd='xbp diag'
alias xm='xbp monitor check'
alias xl='xbp tail'
alias xp='xbp ports'
alias xs='xbp services'
```
```bash
eval "$(xbp --completion bash)"
```
```bash
eval "$(xbp --completion zsh)"
```
```bash
xbp --completion fish | source
```
1. **Use `--debug`** for troubleshooting
2. **Pipe to `jq`** for JSON formatting
3. **Combine with `watch`** for monitoring
4. **Use `&&` and `||`** for conditional execution
5. **Create aliases** for frequent commands
6. **Save output** for later analysis
7. **Use environment variables** for configuration
```bash
xbp diag
xbp service dev api
xbp tail
```
```bash
xbp diag
xbp service build api
xbp service start api
xbp monitor start
```
```bash
xbp diag --debug
xbp ports -p 3000
xbp logs api
xbp monitor check
```
```bash
xbp monitor start &
xbp tail --ship &
watch xbp ports
```
- Commands are dispatched via `src/cli/router.rs` into domain handlers under `src/cli/handlers/`.
- Shared CLI context lives in `src/cli/app.rs`; unified error type is `CliError` (`src/cli/error.rs`).
- Subprocess work should use `sdk::command::CommandRunner` (NGINX migrated; PM2 migration in progress).
- API management: `xbp api install --port 8080` writes/enables `xbp-api.service`; the API exposes `/routes`, `/proxy/{domain}/...`, and `/metrics` (Prometheus).
- [Configuration Guide](/docs/configuration)
- [Installation Guide](/docs/installation)
- [Command Documentation](/docs/commands/diag)
- [Guides](/docs/guides/monitoring)