Agent Guide

AGENTS.md

This project runs on nSelf. Use the nself CLI for every backend operation; do not hand-write Docker Compose files or run SQL against the database directly.

Two commands

nself init     # scaffold the project (no prompts when NSELF_NONINTERACTIVE=1)
nself start    # build and run the stack

Run nself doctor when something fails and nself status to see what is up.

Commands

• nself init: Initialize a new nSelf project
• nself start: Boot your nSelf stack
• nself stop: Gracefully shut down all services or specific services
• nself restart: Smart restart with config change detection
• nself status: Show health status of all services
• nself logs: View and filter service logs
• nself doctor: Run comprehensive system diagnostics
• nself build: Compose your infrastructure from .env
• nself reset: Stop containers, remove all data volumes, and clean generated files
• nself clean: Remove generated artifacts (docker-compose.yml, nginx configs, build cache)
• nself add: Install a plugin or bundle
• nself remove: Remove an installed plugin or bundle
• nself config: Manage project configuration
• nself db: Database operations: migrations, backups, restore, seed, shell
• nself backup: Backup operations: create, list, restore, verify, prune, config, status, init-key
• nself deploy: Deploy the stack to a target environment
• nself update: Update the nSelf CLI and admin UI
• nself license: Manage license keys for nSelf product bundles
• nself mcp: Start the nSelf MCP server
• nself exec: Execute a command inside a service container

Run nself <command> --help for flags, nself help --json for the full machine-readable command registry.

Output and exit codes

• --json prints one document: {"schema_version":"1","command":"<path>","data":{...}} on success, or {"schema_version":"1","command":"<path>","error":{...}} on failure. Parse stdout only; messages go to stderr.
• Exit codes: 0 ok, 1 user error (bad input), 2 infrastructure error (Docker, network), 3 auth error, 4 destructive action blocked.
• Every error carries a code (E401) with a fix: nself help --json and the nself://errors MCP resource list them.

MCP

nself mcp serves the CLI as MCP tools over stdio. Register it with your client: nself mcp setup --client claude-code --write (also cursor; codex and generic print the config). Tools mirror the commands above; destructive tools ask for a confirmation round trip first.