CLI Reference

Complete reference for all slipp commands. Commands follow a consistent pattern:

Singular = action (slipp run, slipp deploy)
Plural = manage resources (slipp runs, slipp secrets)

slipp [OPTIONS] COMMAND [ARGS]

Global Options

Option	Description
`-v, --verbose`	Enable verbose logging
`-o, --output`	Output format: `table` (default), `json`
`-V, --version`	Show version and exit
`--help`	Show help message

Operations

Commands for monitoring and managing deployed services.

ps

List running services across registered projects (like docker ps).

slipp ps [OPTIONS]

Option	Description
`-p, --project`	Filter by project name
`--refresh`	Force re-discovery (bypass cache)
`--all`	Include system services

Examples

# List all services
slipp ps

# Filter by project
slipp ps -p myproject

# Fresh discovery
slipp ps --refresh

# JSON output
slipp ps -o json

When a host is shared by more than one registered project (see Multiple hosts), the host column lists every owning project’s own label for it, e.g. myserver (alpha), myserver (beta), instead of silently attributing the row to just one of them.

logs

View service logs (journalctl or container logs).

slipp logs <service> [OPTIONS]

Option	Description
`-f, --follow`	Follow log output
`-n, --lines`	Number of lines (default: 50)
`--all`	Include system services in discovery

Examples

# View last 50 lines
slipp logs synapse

# Follow logs
slipp logs synapse -f

# Last 100 lines
slipp logs synapse -n 100

Service lookup grammar

logs, exec, ssh, and status all resolve a bare service name against every registered project’s inventory — there’s no --project flag, and no current-directory scoping. Use the qualified forms to disambiguate:

Form	Resolves to
`service`	Look up in the global service index
`service@host`	Filter by host name
`project:service`	Filter by project name
`project:service@host`	Fully qualified

slipp logs postgres          # ambiguous if two projects share a host
slipp logs myproject:postgres
slipp logs postgres@myserver

If a host is shared by more than one project (see Multiple hosts), an unqualified service name on that host raises an error listing the matches to disambiguate between — this is deliberate, not a bug: there’s no safe way to guess which project’s service you meant.

status

Display detailed service status (like systemctl status).

slipp status <service>

exec

Execute a command on VPS or in a container.

slipp exec "<command>"
slipp exec <service> "<command>"

Option	Description
`-u, --user`	Override user (root, postgres, www-data)

Examples

# Execute on VPS
slipp exec "df -h"

# Execute in container
slipp exec synapse "cat /data/homeserver.yaml"

# Execute as root
slipp exec -u root "systemctl restart nginx"

ssh

Open interactive shell on VPS or container service.

slipp ssh [service]

Option	Description
`-u, --user`	Override user

Examples

# SSH to VPS
slipp ssh

# Shell into container
slipp ssh synapse

# As specific user
slipp ssh -u postgres

host

Output host connection info (pipeable).

slipp host [project]

Option	Description
`--ip`	Output IP only
`--user`	Output user only
`--port`	Output port only

Examples

# Get connection string
slipp host
# Output: slipp@192.168.1.100

# Get IP for scripting
slipp host --ip
# Output: 192.168.1.100

# Specific project
slipp host myproject --ip

Development

Commands for local development workflows.

run

Execute a run profile for local development with remote infrastructure.

slipp run <name> [OPTIONS] [-- ARGS]

Option	Description
`--cmd`	Command (creates/updates profile)
`--env`	Environment variable `KEY=VALUE` (repeatable)
`--vault`	Vault project(s) for secrets (repeatable)
`--tunnel-out`	Reverse tunnel `local_port:domain@host`
`--tunnel-in`	Forward tunnel `service:port@host`
`--proxy`	Proxy route `from@host -> to` (repeatable)
`--tunnel-auth`	HTTP basic auth for tunnel-out routes `user:pass` (bcrypt-hashed before saving)

Create Profile
Use Profile

# Create and run profile
slipp run dev \
  --cmd "npm run dev" \
  --tunnel-out 5173:app.example.com@myserver \
  --vault myproject

# Run saved profile
slipp run dev

# Pass additional args
slipp run dev -- --port 3000

# Override at runtime
slipp run dev --env DEBUG=true

slipp run exits with the wrapped command’s exit code (130 on Ctrl+C), so it’s safe to use in scripts and CI pipelines.

runs

Manage saved run profiles.

Profiles are stored in slipp.yaml under runs: (git-tracked). A profile can inherit from another with extends, and personal overrides can live in the untracked .slipp/runs.local.yaml (same name shadows the tracked profile entirely — not merged field-by-field):

runs:
  dev:
    cmd: npm run dev
    tunnels:
      out: [5173:app.example.com@myserver]
  dev-staging:
    extends: dev # inherits cmd/tunnels, overrides below
    env:
      - VITE_ENV=staging

runs list

slipp runs list

Lists all saved profiles with their commands, vaults, and tunnels.

runs remove

slipp runs remove <name>

Remove a saved run profile.

launch

Generate complete Ansible project from codebase.

slipp launch [OPTIONS]

Option	Description
`-n, --name`	Project name (required)
`-e, --env`	Environment (default: production)
`-d, --dir`	Directories to scan (repeatable)
`--dry-run`	Show what would be done
`--reconfigure`	Re-prompt for inventory config
`--proxy`	Reverse proxy: `auto` (probe host, default), `caddy`, `none`, `wg-manage`
`--public`	Expose via Let’s Encrypt instead of internal CA (`--proxy wg-manage` only)
`--python-extra`	`uv sync --extra` group (Python systemd deploys)
`--exec-args`	Extra ExecStart arguments (Python systemd deploys)
`--health-check`	HTTP path polled after restart; rolls back on failure (systemd deploys)

Example

# Generate Ansible project
slipp launch --name myapp

# Multiple directories
slipp launch --name myapp -d ./frontend -d ./backend

# Different environment
slipp launch --name myapp --env staging

# Expose through wg-manage, publicly, with a rollback-guarded health check
slipp launch --name myapp --proxy wg-manage --public --health-check /healthz

--proxy auto probes the target host: if it’s already a wg-manage hub, services expose through wg-manage; otherwise slipp falls back to a Caddy route. See expose: for how routing is seeded and edited.

generate

Generate specific Ansible project files.

generate dockerfile

slipp generate dockerfile [OPTIONS]

Generate only Dockerfiles for detected services.

generate scaffold

slipp generate scaffold [OPTIONS]

Generate project scaffolding without Dockerfiles.

generate full

Alias for slipp launch — generates the complete project (Dockerfiles + scaffolding).

Option	Description
`-t, --tags`	Ansible tags to run (comma-separated)
`--skip-tags`	Ansible tags to skip (comma-separated)

Option	Description
`-b, --bytes`	Bytes of entropy (default: 32 = 256-bit)
`--base64`	Output as base64 instead of hex
`--ulid`	Output as ULID (ignores —bytes)
`--jwk`	Output as RSA JWK keypair
`--bits`	RSA key size for —jwk (default: 2048)

Option	Description
`-n, --name`	Get template string for secret name

Examples

# Show available vaults
slipp secrets list

# List secrets in project vault
slipp secrets list myproject

# Get template string for specific secret
slipp secrets list myproject db_password
# Output: {{ db_password }}

secrets add

slipp secrets add <name> [target] [OPTIONS]

Option	Description
`-b, --bytes`	Bytes of entropy (default: 32)
`-e, --encoding`	Output encoding: `hex` (default), `base64`, `ulid`
`--jwk`	Generate RSA JWK keypair
`--bits`	RSA key size for —jwk (default: 2048)

Examples

# Add random secret to current project vault
slipp secrets add vault_db_password

# Add to specific project
slipp secrets add vault_api_key myproject

# Add JWK keypair
slipp secrets add vault_signing_key --jwk

secrets sync

slipp secrets sync <path> [OPTIONS]

Scan YAML for {{ vault_* }} references and auto-generate secrets.

Option	Description
`-b, --bytes`	Bytes of entropy (default: 32)
`-e, --encoding`	Output encoding: `hex` (default), `base64`, `ulid`
`-f, --force-existing`	Add missing secrets to an existing vault.yml

Example

slipp secrets sync inventory/host_vars/myhost/vars.yml
# Creates vault.yml with generated secrets for all {{ vault_* }} refs

secrets pull

slipp secrets pull <source> [target] [OPTIONS]

Pull credentials from external source via browser approval flow.

Argument	Description
`source`	Secret source (e.g., `nor-auth`)
`target`	Target vault (project name or path)

Option	Description
`-t, --timeout`	Timeout in seconds (default: 300)

Example

# Pull from nor-auth to current project vault
slipp secrets pull nor-auth

# Pull to specific project
slipp secrets pull nor-auth myproject

# Custom timeout
slipp secrets pull nor-auth --timeout 600

Images

Container image operations.

image push

Push local container image to VPS via SSH.

slipp image push <image> [OPTIONS]

Option	Description
`--host`	Target host/project
`-n, --name`	Rename image on VPS

Examples

# Push image
slipp image push myapp:latest

# Push to specific project host
slipp image push myapp:latest --host myproject

# Rename on push
slipp image push myapp:v1.2.3 --name myapp:latest

images list

List container images on VPS.

slipp images list [OPTIONS]

Option	Description
`--host`	Target host/project
`-f, --filter`	Filter by name pattern

Examples

# List all images
slipp images list

# Filter by pattern
slipp images list --filter "myapp*"

Management

Project and configuration management.

projects

Manage registered projects.

projects list

slipp projects list

List all registered projects with their paths.

projects add

slipp projects add <name> [OPTIONS]

Option	Description
`-i, --inventory`	Inventory file path (auto-detected if not specified)
`--playbook`	Playbook file path (auto-detected if not specified)
`--roles`	Role search directories (auto-detected if not specified)
`--galaxy-path`	Install path for external roles from requirements.yml
`--vault`	Path to vault.yml for secret management
`--runtime`	How the app runs: `systemd`, `docker`, `podman` — set explicitly for projects not scanned/generated by `slipp launch`

Examples

# Auto-detect everything
slipp projects add myapp

# Explicit inventory
slipp projects add myapp -i inventory/hosts

# Full setup
slipp projects add myapp -i inventory/hosts --vault inventory/host_vars/myhost/vault.yml

# External project slipp didn't generate (runtime can't be auto-detected)
slipp projects add myapp --runtime systemd

projects remove

slipp projects remove <name>

Unregister a project.

config

Show current project configuration.

slipp config

Displays:

Project name, inventory, playbook, vault paths
Hosts from inventory
Global registry status

Supports -o json for machine-readable output.

Infrastructure

Provisioning, DNS, domains, and multi-host management. Most of these require a configured provider (slipp providers add) — see Gigahost provisioning.

up

Provision (or reuse an existing host), register a domain, launch, sync DNS, and deploy — one command end-to-end.

slipp up <name> [OPTIONS]

Option	Description
`--host`	Use an existing host IP (skips provisioning)
`--domain`	Domain to register (if available) and deploy to
`--dns`	DNS handling: `auto` (default)
`-e, --env`	Environment name
`--hub`	Make the host a wg-manage hub (via a configured `wg-deploy` checkout) before launch, so `--proxy auto` finds it
`--public`	Expose via Let’s Encrypt instead of internal CA (`--proxy wg-manage` only)

Examples

# Full provision -> domain -> launch -> DNS -> deploy
slipp up myapp --domain myapp.example.com

# Reuse an already-provisioned host, make it a hub, expose publicly
slipp up myapp --host 203.0.113.5 --domain myapp.example.com --hub --public

provision

Order a VPS via Gigahost, bootstrap it, and register it as a slipp project.

slipp provision <name> [OPTIONS]

Option	Description
`-e, --env`	Environment name

Writes a minimal inventory pointing at the new server’s IP and registers the project — slipp launch or slipp deploy picks up from there.

server

Out-of-band server operations (no SSH needed — talks to the provider API directly).

slipp server status <name_or_ip>
slipp server reboot <name_or_ip> [--force]
slipp server install <name_or_ip> [--force]

install wipes and reinstalls the server’s OS, then re-bootstraps it. If a previous install/bootstrap was interrupted, re-running the same command resumes from saved state instead of prompting to wipe again.

servers

slipp servers list

List VPS servers across configured providers (no SSH needed).

providers

Manage infrastructure providers: gigahost, pangolin, wg-deploy.

slipp providers add <name>
slipp providers list
slipp providers remove <name>

Examples

# Prompts for and verifies a Gigahost API key
slipp providers add gigahost

# Prompts for a Pangolin session cookie (stopgap until the Integration API)
slipp providers add pangolin

# Verifies a local wg-deploy checkout (see providers add wg-deploy --help)
slipp providers add wg-deploy

slipp providers list
slipp providers remove pangolin

domains

Domain availability, registration, and listing (.no only, via Gigahost).

slipp domains check <domain>
slipp domains register <domain>
slipp domains list

register prompts for registrant info and only proceeds if check reports the domain available.

dns

DNS record management (via the configured DNS provider).

slipp dns sync
slipp dns list <domain>

sync converges the DNS zone + A record for the current project’s primary host domain to its ansible_host IP — creates the zone if it doesn’t exist yet.

resources

Manage exposed services: wg-manage strays (if the project’s host is a wg-manage hub) or public Pangolin resources otherwise.

slipp resources sync [OPTIONS]
slipp resources list
slipp resources remove <name> [--force]

Option	Description
`--site`	Pangolin site name/niceId/siteId (Pangolin projects only)
`--dry-run`	Show what would change

For wg-manage, sync only prunes stray entries left behind by a rename/removal — adds/updates happen at deploy time via the wg-manage-exposure role. list/remove are scoped to entries labeled slipp:<project_name>; a foreign-labeled entry is never touched. For Pangolin, sync converges a public Resource+Target from the project’s inventory (app_domain/ansible_host/app_port) and requires --site.

hosts

Manage secondary deploy hosts for multi-host projects. The interactive slipp launch prompt only ever creates the primary host — additional hosts are added here.

slipp hosts add <name> --host <ip> [OPTIONS]
slipp hosts list
slipp hosts remove <name>

Option	Description
`--host`	IP address or domain for SSH connection (required)
`--user`	SSH username (default: `slipp`)
`--port`	SSH port (default: `22`)
`--runtime`	How the app runs: `systemd`, `docker`, `podman`

Example

slipp hosts add worker --host 203.0.113.9 --runtime docker
# Then assign a service to it: expose: <service>: host: worker in
# slipp.yaml, and run: slipp launch --reconfigure

Adding a host with an IP already used within this project’s own inventory hard-fails (identity collision). An IP already used by a different project is allowed with an informational notice — see Multiple hosts.

Bootstrap

VPS bootstrap operations for initial setup.

bootstrap account

Create slipp service account on VPS.

slipp bootstrap account <host> [OPTIONS]

Option	Description
`--root-user`	Root user for initial connection (default: root)
`--ssh-key`	SSH private key path
`-p, --port`	SSH port (default: 22)
`--user`	Service account name (default: slipp)
`--dry-run`	Show what would be done

Example

slipp bootstrap account 192.168.1.100 --port 22

# Dry run first
slipp bootstrap account myserver.com --dry-run

This command:

Creates the slipp user account
Copies SSH keys from root
Configures passwordless sudo
Verifies the setup

bootstrap proxy

Setup dev proxy infrastructure for --tunnel-out.

slipp bootstrap proxy <host> [OPTIONS]

Option	Description
`-e, --email`	Email for Let’s Encrypt certificates (required)
`-p, --fallback-port`	Port for existing HTTPS service (default: 9443)

Example

slipp bootstrap proxy myproject --email admin@example.com

Installs Caddy dev proxy for routing production domains to local tunnels.

bootstrap registry

Setup container registry authentication on VPS.

bootstrap registry ghcr

slipp bootstrap registry ghcr [OPTIONS]

Option	Description
`--host`	Target host/project
`-u, --user`	GitHub username
`-t, --token`	GitHub PAT (or set `GITHUB_TOKEN`)

bootstrap registry dockerhub

slipp bootstrap registry dockerhub [OPTIONS]

Option	Description
`--host`	Target host/project
`-u, --user`	Docker Hub username
`-t, --token`	Docker Hub token (or set `DOCKER_TOKEN`)

Examples

# GitHub Container Registry
slipp bootstrap registry ghcr --user myuser

# Docker Hub
slipp bootstrap registry dockerhub --user myuser

Deploy

Execute Ansible playbook to deploy services.

slipp deploy [target] [preset] [OPTIONS]

Argument	Description
`target`	Environment name or tag preset (default: production)
`preset`	Tag preset when using `slipp deploy <env> <preset>`

Option	Description
`-n, --name`	Project name (creates/updates slipp.yaml)
`--dry-run`	Show what would be done
`-i, --inventory`	Custom inventory file path
`--playbook`	Custom playbook file path
`--vault`	Path to vault file
`-r, --requirements`	Path to requirements.yml
`--roles`	Role search directories (repeatable)
`--galaxy-path`	Install path for external roles (default: `roles/galaxy`)
`--force-requirements`	Force reinstall roles/collections
`-t, --tags`	Ansible tags to run
`--skip-tags`	Ansible tags to skip
`--runtime`	How the app runs: `systemd`, `docker`, `podman` — set explicitly for projects not scanned/generated by `slipp launch`

Examples

# Deploy with defaults
slipp deploy

# Use tag preset
slipp deploy install

# Deploy to staging with preset
slipp deploy staging install

# First-time setup
slipp deploy --name myproject -i inventory/hosts

# Dry run
slipp deploy --dry-run

Other

logo

slipp logo [--save <file>] [--theme <name>]

Display the slipp ASCII logo, or export it to an HTML file.