Core CLI Commands

The nself CLI is the primary interface for managing your backend infrastructure. This guide covers all core commands for project initialization, service management, and configuration.

New Commands (v0.3.8)

Enterprise-Grade Features v0.3.8

Version 0.3.8 introduces enterprise-grade features with 33 CLI commands while maintaining the simplicity of the 3-command quick start.

# Validation and monitoring
nself validate      # Advanced configuration validation
nself monitor       # Live monitoring dashboard
nself metrics       # Comprehensive metrics collection

# Container operations
nself exec          # Secure container command execution
nself scale         # Intelligent resource scaling

# Backup and recovery
nself backup        # Advanced backup management (10+ subcommands)
nself rollback      # Comprehensive rollback system

# Example usage
nself exec postgres psql -U postgres -d mydb
nself scale hasura --replicas 3
nself backup create --name "pre-deployment"
nself rollback --to "2025-08-17-10:00"

New Commands (v0.3.6)

Enhanced Command Structure v0.3.6

Version 0.3.6 introduces cleaner, more intuitive primary commands while maintaining 100% backward compatibility.

# New primary commands (recommended)
nself start    # Start all services
nself stop     # Stop all services

# Legacy commands (still fully supported)
nself up       # Alias for 'start'
nself down     # Alias for 'stop'

# Your existing scripts continue to work without changes!

New Commands (v0.3.5)

SSL Management Commands v0.3.5

Complete SSL/HTTPS support with automatic certificate generation, dual domain support, and green lock browser compatibility.

# Bootstrap SSL certificates (initial setup)
nself ssl bootstrap

# Check SSL certificate status
nself ssl status

# Renew SSL certificates (for Let's Encrypt and public certs)
nself ssl renew

# Install root CA and enable browser trust
nself trust

# Check trust status
nself trust status

Enhanced Commands (v0.3.3 & v0.3.4)

Docker Resource Management (v0.3.3)

Clean up Docker resources with precision to reclaim disk space and maintain system health.

# Clean images and build cache
nself clean

# Clean all resources (nuclear option)
nself clean -a

# Clean specific resource types
nself clean -c    # Clean containers
nself clean -i    # Clean images
nself clean -v    # Clean volumes
nself clean -n    # Clean networks

# Combine options
nself clean -c -i -v  # Clean containers, images, and volumes

Enhanced Commands (v0.3.0 - v0.3.4)

Intelligent Auto-Fix System (v0.3.3)

nself now includes an intelligent auto-fix system that automatically resolves common configuration and runtime issues.

# Auto-fix is now enabled by default
nself start  # Automatically fixes issues during startup

# Disable auto-fix for manual control
ALWAYS_AUTOFIX=false nself start

# Run doctor command for comprehensive health checks
nself doctor

# The system will automatically:
# - Fix port conflicts
# - Generate missing service files
# - Resolve configuration issues
# - Restart unhealthy services
# - Create missing Dockerfiles

v0.2.x Commands

Email Configuration (v0.2.4)

Set up email providers for production use with an interactive wizard.

# Interactive email setup wizard
nself email setup

# The wizard will guide you through:
# - Selecting your email provider (SendGrid, AWS SES, Mailgun, etc.)
# - Configuring SMTP settings
# - Testing the configuration
# - Automatically updating your .env.local file

SSL Certificate Trust (Enhanced in v0.3.5)

Eliminate browser security warnings with automatic SSL certificate installation and dual domain support.

# Install SSL certificate authority and enable browser trust
nself trust

# Check trust status
nself trust status

# This command will:
# - Install mkcert if not present
# - Create a local certificate authority
# - Generate trusted certificates for both *.localhost and *.local.nself.org
# - Install CA certificate in system trust store
# - Enable green lock for all nself services
# - Support cross-platform (macOS, Windows, Linux)

Configuration Diff (v0.2.3)

View differences between your current configuration and the generated Docker Compose files.

# Show configuration differences
nself diff

# Compare against specific environment
nself diff --env production

# Show only specific service differences
nself diff --service hasura

Installation and Setup

Installing nself CLI

# Install via install script
curl -fsSL https://raw.githubusercontent.com/acamarata/nself/main/install.sh | bash

# Manual installation
wget https://github.com/acamarata/nself/releases/latest/download/nself-linux-amd64.tar.gz
tar -xzf nself-linux-amd64.tar.gz
sudo mv nself /usr/local/bin/

# Verify installation
nself version

Global Options

# Global flags available for all commands
nself [command] [flags]

# Common global flags:
--verbose, -v    # Enable verbose output
--quiet, -q      # Suppress output
--help, -h       # Show help information
--version        # Show version information
--config         # Specify config file path
--env            # Specify environment (development, staging, production)

Project Management

Initialize a New Project

# Initialize new nself project
nself init [project-name]

# Initialize with template
nself init --template blog
nself init --template ecommerce
nself init --template api-only
nself init --template minimal

# Initialize in current directory
nself init .

# Initialize with specific configuration
nself init my-app --postgres-password "secure123" --enable-redis

Project Information

# Show project information
nself info

# Show current configuration
nself config show

# Show project structure
nself structure

# Show all available services
nself services list

Service Management

Starting and Stopping Services

# Start all services
nself up

# Start specific services
nself up postgres hasura
nself up --services postgres,redis,hasura

# Start in detached mode (background)
nself up -d

# Start with recreation of containers
nself up --recreate

# Start with build
nself up --build

# Stop all services
nself down

# Stop specific services
nself down postgres hasura

# Stop and remove volumes (⚠️ destroys data)
nself down --volumes

# Force stop (kill containers)
nself down --force

Service Status and Information

# Check status of all services
nself status

# Check status with resource usage
nself status --resources

# Check status of specific services
nself status postgres hasura redis

# Show detailed information
nself status --verbose

# Output in JSON format
nself status --output json

Restarting Services

# Restart all services
nself restart

# Restart specific services
nself restart hasura
nself restart postgres redis

# Rolling restart (one service at a time)
nself restart --rolling

# Restart with rebuild
nself restart --build

Configuration Management

Building Configuration

# Build Docker Compose configuration
nself build

# Build for specific environment
nself build --env production
nself build --env staging

# Build with specific template
nself build --template docker-compose.custom.yml

# Validate configuration before building
nself build --validate

# Show generated configuration without writing
nself build --dry-run

Configuration Commands

# Show current configuration
nself config show

# Show configuration for specific environment
nself config show --env production

# Validate configuration
nself config validate

# Set configuration value
nself config set POSTGRES_PASSWORD new_password
nself config set --env production DOMAIN myapp.com

# Get configuration value
nself config get POSTGRES_PASSWORD

# List all configuration keys
nself config list

# Generate configuration template
nself config generate --env production

Environment Management

Environment Operations

# List available environments
nself env list

# Show current environment
nself env current

# Switch environment
nself env switch production
nself env switch staging

# Create new environment configuration
nself env create testing

# Copy environment configuration
nself env copy development staging

# Remove environment
nself env remove testing

Production Deployment

# Generate production configuration
nself prod

# Generate production config with domain
nself prod --domain myapp.com

# Generate with specific services
nself prod --services postgres,hasura,redis

# Generate with SSL enabled
nself prod --ssl --letsencrypt

# Generate for specific cloud provider
nself prod --provider aws
nself prod --provider gcp
nself prod --provider azure

Logging and Debugging

Log Management

# View logs from all services
nself logs

# View logs from specific services
nself logs postgres
nself logs hasura redis

# Follow logs in real-time
nself logs --follow
nself logs -f postgres

# Show last N lines
nself logs --tail 100
nself logs -n 50 hasura

# Filter logs by time
nself logs --since "2024-01-01"
nself logs --since "1h"
nself logs --since "30m"

# Show timestamps
nself logs --timestamps

Debugging Commands

# Execute command in service container
nself exec postgres psql -U postgres
nself exec hasura hasura-cli console
nself exec redis redis-cli

# Execute with specific user
nself exec --user root postgres bash

# Execute interactively
nself exec -it postgres bash

# Debug specific service
nself debug postgres

# Show service resource usage
nself resources

# Show Docker system information
nself system info

Data Management

Reset and Cleanup

# Reset all data (⚠️ destroys everything)
nself reset

# Reset specific services
nself reset postgres
nself reset --services postgres,redis

# Reset with confirmation prompt
nself reset --interactive

# Soft reset (keeps database data)
nself reset --soft

# Reset and rebuild
nself reset --rebuild

Volume Management

# List volumes
nself volumes list

# Create volume backup
nself volumes backup postgres_data

# Restore volume from backup
nself volumes restore postgres_data backup_20240101.tar.gz

# Remove unused volumes
nself volumes prune

# Show volume usage
nself volumes usage

Update and Maintenance

Updates

# Update nself CLI
nself update

# Update to specific version
nself update --version v0.3.0

# Check for available updates
nself update --check

# Update service images
nself update --images

# Update specific service image
nself update postgres --image postgres:15

Maintenance Commands

# Health check all services
nself health

# Health check with detailed output
nself health --verbose

# Check service dependencies
nself deps check

# Show system requirements
nself requirements

# Clean up Docker resources
nself cleanup

# Optimize Docker images
nself optimize

Service-Specific Commands

Docker Integration

# Run raw Docker Compose commands
nself docker-compose ps
nself docker-compose logs postgres

# Execute Docker commands
nself docker ps
nself docker images

# Show generated Docker Compose file
nself docker-compose config

# Pull latest images
nself pull

# Build custom images
nself build-images

Network Commands

# List networks
nself network list

# Show network configuration
nself network info

# Test network connectivity
nself network test

# Show port mappings
nself ports

# Check open ports
nself ports --check

Scripting and Automation

Batch Operations

# Run multiple commands in sequence
nself batch --commands "build,up,status"

# Execute from script file
nself batch --file deploy.nself

# Conditional execution
nself batch --if-healthy "restart hasura"

# Parallel execution
nself batch --parallel "logs postgres,logs hasura"

Watch Mode

# Watch for configuration changes and rebuild
nself watch

# Watch specific files
nself watch --files ".env.local,schema.dbml"

# Watch and restart services on change
nself watch --restart

# Watch with custom command
nself watch --command "build && restart hasura"

Output Formatting

Output Options

# JSON output
nself status --output json
nself config show --output json

# YAML output
nself config show --output yaml

# Table output
nself status --output table

# Quiet output (minimal)
nself up --quiet

# Verbose output (detailed)
nself up --verbose

Advanced Usage

Plugin System

# List available plugins
nself plugins list

# Install plugin
nself plugins install monitoring

# Update plugin
nself plugins update monitoring

# Remove plugin
nself plugins remove monitoring

# Run plugin command
nself monitoring dashboard

Custom Templates

# Create custom template
nself template create my-template

# Use custom template
nself init --template ./my-template

# List available templates
nself template list

# Validate template
nself template validate my-template

Error Handling and Recovery

Common Issues

# Check for common configuration issues
nself doctor

# Verify system requirements
nself requirements --check

# Fix permissions
nself fix permissions

# Repair configuration
nself repair

# Force cleanup and restart
nself emergency-reset

Backup and Recovery

# Create full backup
nself backup create

# Create backup with name
nself backup create --name "before-migration"

# List backups
nself backup list

# Restore from backup
nself backup restore "before-migration"

# Restore specific services
nself backup restore --services postgres,redis

Configuration File Reference

nself.yaml Configuration

# nself.yaml - project configuration file
project:
  name: my-backend
  version: "1.0.0"
  description: "My nself backend"

environments:
  development:
    config_file: .env.local
  staging:
    config_file: .env.staging
  production:
    config_file: .env.prod-template # copy to .env before deployment

services:
  postgres:
    enabled: true
    image: postgres:15
    ports:
      - "5432:5432"
  
  hasura:
    enabled: true
    depends_on:
      - postgres
    ports:
      - "8080:8080"

hooks:
  pre_up:
    - nself db migrate
  post_up:
    - nself db seed
  pre_down:
    - nself db backup

Copy .env.prod-template to .env before deployment.

Command Examples

Development Workflow

# Start development environment
nself init my-app
cd my-app
nself up

# Make changes, rebuild and restart
nself build && nself restart hasura

# View logs while developing
nself logs -f hasura

# Clean up when done
nself down

Production Deployment

# Prepare production configuration
nself prod --domain myapp.com --ssl

# Deploy to server
scp -r . server:/opt/myapp/
ssh server "cd /opt/myapp && nself up -d"

# Check deployment status
ssh server "cd /opt/myapp && nself status"

# View production logs
ssh server "cd /opt/myapp && nself logs --tail 100"

Troubleshooting Workflow

# Check overall health
nself doctor
nself health --verbose

# Identify failing service
nself status
nself logs failing-service

# Restart problematic service
nself restart failing-service

# If all else fails, reset
nself reset --soft

Best Practices

Command Usage

• Use Specific Services: Target specific services instead of all when possible
• Check Status First: Always check status before making changes
• Use Dry Run: Use --dry-run flag to preview changes
• Keep Logs: Monitor logs during operations

Environment Management

• Environment Separation: Use different environments for development/staging/production
• Configuration Validation: Validate configuration before deployment
• Backup Before Changes: Create backups before major changes
• Monitor Resources: Check resource usage regularly

Keyboard Shortcuts

Interactive Mode

# When using nself logs -f or similar:
Ctrl+C    # Exit/interrupt
Ctrl+Z    # Suspend
Ctrl+L    # Clear screen

# When using nself exec -it:
Ctrl+P, Ctrl+Q    # Detach from container
Ctrl+D            # Exit container

Next Steps

Now that you understand the core CLI commands:

• Database CLI Commands - Database-specific operations
• Service CLI Commands - Service management commands
• Production CLI Commands - Production deployment commands
• Configuration - Detailed configuration options

The nself CLI is designed to be intuitive and powerful. Master these core commands to efficiently manage your backend infrastructure.