README.md
Rama main · réplica de lectura del repositorio original.
# ɳSelf CLI
[](https://github.com/nself-org/cli/releases/latest)
[](https://go.dev/)
[](LICENSE)
[](#prerequisites)
[](https://www.docker.com/get-started)
[](https://github.com/nself-org/cli/actions)
[](https://github.com/nself-org/cli/actions/workflows/security-scan.yml)
[](https://codecov.io/gh/nself-org/cli)
<div align="center">
**Self-hosted backend in 5 minutes**
Complete, production-ready backend stack — PostgreSQL, GraphQL API, Authentication, and Nginx — launched from a single command. Extend with free and paid plugins (`nself plugin count` for current totals). MIT licensed core, forever.
**v<!-- BEGIN GENERATED:facts:version -->1.4.15<!-- END GENERATED:facts:version --> is out.** See the [changelog](.github/wiki/Changelog.md) for what shipped. [Release notes](https://github.com/nself-org/cli/releases/latest)
```bash
brew install nself-org/nself/nself
```
[Quick Start](#quick-start) · [The Stack](#the-stack) · [Plugins](#plugins) · [Pricing](#pricing) · [Docs](https://nself.org/docs)
</div>
---
## What is ɳSelf?
ɳSelf is a self-hosted backend platform that gives you the equivalent of a commercial Backend-as-a-Service on your own infrastructure. Run it locally, on a VPS, or on any cloud provider (Kubernetes: planned — see the [k8s plugin](https://nself.org/plugins)).
You get Postgres, Hasura GraphQL, nHost Auth, and Nginx as the always-on core. Add optional services like Redis, MinIO, and Search when you need them. Extend everything with free MIT plugins and paid plugins covering AI, messaging, media processing, billing, and more — run `nself plugin count` for current totals.
The nself CLI is a single Go binary. No runtime dependencies beyond Docker.
---
## Quick Start
```bash
# Install (macOS)
brew install nself-org/nself/nself
# Install (Linux / WSL2)
curl -fsSL https://install.nself.org | bash
# Create a project and start the stack
mkdir my-backend && cd my-backend
nself init
nself start
```
With `NSELF_V15=1`, bare `nself` prints the next command for the current project, followed by the command list.
Your backend is running:
- GraphQL API: `https://api.local.nself.org`
- Auth: `https://auth.local.nself.org`
- Storage: `https://storage.local.nself.org`
- Admin UI: `http://localhost:3021`
All `*.local.nself.org` domains resolve to `127.0.0.1`. Automatic SSL — no browser warnings.
---
## The Stack
ɳSelf organizes services into three tiers. This ordering matters everywhere: Core first, Optional second, Plugins last.
### Core Services (always on — 4 services)
These four services start with every `nself start` and cannot be disabled. They are the permanent foundation.
| Service | Role |
|---------|------|
| **PostgreSQL** | Primary database (pgvector, PostGIS, TimescaleDB) |
| **Hasura** | Instant GraphQL API with permissions, subscriptions, and metadata |
| **Auth** (nHost) | JWT-based authentication — 13 OAuth providers (Google, GitHub, Microsoft, etc.) |
| **Nginx** | Reverse proxy and SSL terminator — the only external-facing process |
All internal services bind to `127.0.0.1`. Nginx is the only external-facing process.
### Optional Services (enable per project — 6 services)
These services are first-class and CLI-managed. Toggle them in `.env` and rebuild.
| Service | Toggle | Role |
|---------|--------|------|
| **Redis** | `REDIS_ENABLED=true` | Caching, sessions, queues |
| **MinIO** | `MINIO_ENABLED=true` | S3-compatible object storage |
| **Search** | `MEILISEARCH_ENABLED=true` | Full-text search (MeiliSearch) |
| **Email** | `MAIL_ENABLED=true` | Email service — 16+ providers (SendGrid, SES, Mailgun, Postfix, and more) |
| **Functions** | `FUNCTIONS_ENABLED=true` | Serverless runtime |
| **Admin** | `NSELF_ADMIN_ENABLED=true` | Local GUI companion at `localhost:3021` |
```bash
nself service list # see all available services and their status
nself service enable redis # enable a service
nself build && nself restart
```
### Plugins (drop-in expansions)
Plugins are the extension layer — install what you need, remove what you don't.
- **Free MIT plugins** — no license key required
- **Paid plugins** — require a membership key (starting at $0.99/mo)
- Run `nself plugin count` for current totals
```bash
nself plugin install monitoring # free: Prometheus + Grafana + Loki
nself plugin install search # free: MeiliSearch full-text search
nself plugin install cron # free: scheduled job execution
nself license set nself_pro_xxxxx
nself plugin install ai # paid: multi-provider LLM gateway
nself plugin install livekit # paid: live video and audio
nself plugin install claw # paid: AI assistant backend
```
See [Plugins](#plugins) for the full inventory.
---
## Key Features
- Complete backend in under 5 minutes on any machine with Docker
- Full control from the terminal over every service and operation
- Built-in CI gate (`nself ci`) — replaces external CI for merge enforcement
- Core services always-on; optional services enable with one line in `.env`
- Plugins extend the stack without touching core config (`nself plugin count` for current totals)
- Multi-tenancy, row-level security, and org management built in
- Stripe/Paddle billing integration included
- White-label support — custom domains, branding, email templates
- Monitoring bundle (Prometheus, Grafana, Loki, Tempo, and 6 more) via the `monitoring` plugin
- Automated SSL via Let's Encrypt in production; trusted local certs in dev
- Security hardening runs automatically on install, update, deploy, and daily — always free
- Multi-environment support: local, staging, and production from one install
- 40+ custom service templates (Express, FastAPI, NestJS, Gin, Rust, gRPC, and more)
- One-command migration from Supabase, Nhost, or Firebase
---
## Installation
### macOS (Homebrew)
```bash
brew install nself-org/nself/nself
```
### Linux
```bash
curl -fsSL https://install.nself.org | bash
```
### Windows
WSL2 is required. Once WSL2 is set up, use the Linux installer above inside your WSL2 terminal.
The installer auto-detects existing installations, checks for Docker, downloads the binary to `~/.nself/bin`, and adds nself to your PATH.
### Docker
```bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
-v ~/.nself:/root/.nself nself/nself version
```
### Build from source
```bash
git clone https://github.com/nself-org/cli
cd cli
make build
make install # copies nself to /usr/local/bin
```
Requires Go 1.22+ and GNU make.
### Secure install (recommended for CI and production)
The installer always fetches `checksums.txt` from the same GitHub release and verifies the SHA-256 of the downloaded tarball before extracting. Installation aborts loudly on any mismatch.
For the most paranoid setups, pin the expected SHA-256 in your shell or CI config:
```bash
# Obtain the expected checksum for a specific release (replace X.Y.Z with that release):
curl -fsSL https://github.com/nself-org/cli/releases/download/vX.Y.Z/checksums.txt
# Install with a pinned version and pinned SHA-256:
NSELF_VERSION=vX.Y.Z \
NSELF_INSTALL_PIN_SHA256=<sha256-from-checksums.txt> \
curl -fsSL https://install.nself.org | bash
```
This defends against a compromised release page: even if the tarball at the release URL is replaced, the pinned SHA will not match and the install fails.
### Update
```bash
nself update # detects your install method and updates in place
```
---
## 5-Minute Tutorial
```bash
# 1. Install
# macOS: brew install nself-org/nself/nself
# Linux: curl -fsSL https://install.nself.org | bash
# 2. Create a project
mkdir my-backend && cd my-backend
# 3. Initialize with defaults (or use --wizard for interactive setup)
nself init
# 4. Generate Docker configs from your .env
nself build
# 5. Start the stack
nself start
# 6. Check everything is healthy
nself status
nself urls
```
Your core backend is running. Add optional services:
```bash
# Enable Redis and full-text search
nself service enable redis
nself service enable search
nself build && nself restart
# Install a free plugin
nself plugin install monitoring # Prometheus + Grafana + Loki
# Set a pro license and install an AI plugin
nself license set nself_pro_xxxxxx
nself plugin install ai
nself build && nself restart
```
---
## CLI Command Reference
ɳSelf provides a small set of top-level commands organized by domain. The core verbs are <!-- BEGIN GENERATED:facts:verbs -->`init`, `start`, `stop`, `restart`, `status`, `logs`, `doctor`, `build`, `reset`, `clean`, `add`, `remove`, `config`, `db`, `backup`, `deploy`, `update`, `license`, `mcp`, `exec`<!-- END GENERATED:facts:verbs -->.
Current surface:
<!-- truth: exempt tools/facts renders this count from the command registry -->
<!-- BEGIN GENERATED:facts:top-level -->20 top-level commands in v1.5 mode, `NSELF_V15=1`<!-- END GENERATED:facts:top-level -->
Full reference: [nself.org/docs/cli](https://nself.org/docs/cli).
### Stack lifecycle
```
nself init Initialize a new nSelf project
nself build Generate Docker configs from .env
nself start Boot the stack (alias: nself up)
nself stop Stop the stack (alias: nself down)
nself restart Smart restart with change detection
nself reset Stop, remove volumes, clean generated files
```
### Services and config
```
nself service Manage optional services (list, enable, disable)
nself config Manage project configuration (show, get, set, validate)
nself env Multi-environment management (use, list, diff, copy)
nself promote Promote environment to another (staging to prod)
```
### Plugins and licensing
```
nself plugin Plugin management (install, remove, update, list, status, marketplace)
nself license License key management (set, show, validate, clear)
```
### Database
```
nself db Database operations:
migrate (up/down/status/create)
seed, backup, restore, shell, drop, reset
rls, pitr, pgbouncer, audit, soft-delete, fk-index, fixtures
```
### Security and operations
```
nself security Security audit, setup, scan, and status
nself secrets Encrypted secret management (age encryption)
nself backup Backup operations (create, list, restore, verify, prune)
nself ssl SSL certificate management (status, renew, setup, add)
nself doctor System diagnostics with auto-repair (--deep for full hardening checks)
nself health Health checks (check, watch, history)
```
### Monitoring and observability
```
nself status Service health status (--deep for extended probes)
nself logs View and filter service logs
nself urls List all service URLs
nself monitor Monitoring stack management
nself alerts Manage Prometheus alert rules and silences
nself watchdog Self-healing container watchdog with circuit breaker
```
### Infrastructure
```
nself deploy Deploy to environment
nself tenant Tenant management (create, upgrade, suspend, destroy, audit)
nself admin Open the Admin UI (start, connect)
nself dr Disaster recovery (drill, promote-standby, rollback, fence)
nself waf Web Application Firewall (enable, mode, report)
```
Run `nself help <command>` for subcommand details.
---
## Comparison
| | ɳSelf | Supabase | Nhost | Coolify | Firebase |
|---|:---:|:---:|:---:|:---:|:---:|
| Fully self-hosted | Yes | Limited | Limited | Yes | No |
| MIT licensed core | Yes | Partial | Partial | Apache 2.0 | No |
| Multi-tenancy built-in | Yes | No | No | No | No |
| Built-in billing integration | Yes | No | No | No | No |
| White-label support | Yes | No | No | No | No |
| Setup time | ~5 min | 30+ min | 30+ min | 15+ min | N/A |
| Plugin ecosystem | Free and licensed plugins (`nself plugin count`) | Limited | Limited | App templates | No |
| Deploy anywhere | Yes | Cloud-first | Cloud-first | Yes | No |
| Data ownership | Full | Shared | Shared | Full | No |
---
## Pricing
The nself CLI and the free MIT plugins are fully FOSS. Free forever, including commercial use. Licensed plugins require a membership key.
| Tier | Monthly | Annual | What's included |
|------|---------|--------|-----------------|
| Free | $0 | $0 | Core CLI + free MIT plugins |
| Bundle | $0.99/mo | $9.99/yr | All licensed plugins of one Bundle (ɳChat, ɳClaw, ɳFamily, ɳSentry, or ClawDE); the Task Bundle is free |
| ɳSelf+ | $3.99/mo | $39.99/yr | Every bundle + all apps + priority support |
| ɳCloud | custom | custom | Managed hosting + ɳSelf+ license + cloud-exclusive features |
Annual pricing saves ~17% vs monthly. See [nself.org/pricing](https://nself.org/pricing) for current offers and migration from prior tiers.
```bash
nself license set nself_pro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
nself plugin install ai
```
---
## Plugins
### Free plugins (MIT, no key required)
Install any free plugin with `nself plugin install <name>`:
| Plugin | Category | What it does |
|--------|----------|-------------|
| `backup` | Infrastructure | Automated PostgreSQL backup with pruning and cloud storage |
| `cron` | Automation | Scheduled job execution with HTTP callbacks |
| `feature-flags` | Infrastructure | Feature flag management with targeting rules |
| `github` | Development | GitHub repository, issue, and workflow integration |
| `jobs` | Infrastructure | PostgreSQL-backed background job queue |
| `monitoring` | Infrastructure | Full observability stack: Prometheus, Grafana, Loki, and 7 more services |
| `notify` | Communication | Email (SMTP) and webhook notifications |
| `search` | Infrastructure | Full-text search (PostgreSQL FTS + MeiliSearch) |
| `stripe` | Commerce | Stripe payment data sync and webhooks |
| `webhooks` | Communication | Outbound webhook delivery with retry and HMAC signing |
| + 15 more | Various | content-acquisition, content-progress, donorbox, github-runner, invitations, link-preview, mdns, notifications, paypal, shopify, subtitle-manager, tokens, torrent-manager, vpn, webhooks |
Full inventory: [nself.org/plugins](https://nself.org/plugins)
### Licensed plugins (license-gated, starting at $0.99/mo)
```bash
nself license set nself_pro_xxxxxx
nself plugin install <name>
nself build
```
Categories include AI and intelligence, real-time communication, media processing, billing, compliance, content management, multi-tenancy, and more. Notable plugins:
- `ai` — multi-provider LLM gateway (OpenAI, Anthropic, Cohere, local models)
- `claw` — AI personal assistant backend with infinite memory (pgvector + ltree)
- `livekit` — live video and audio rooms
- `chat` — real-time messaging
- `media-processing` — encoding, transcoding, thumbnail generation
- `streaming` — HLS/DASH adaptive streaming
- `compliance` — GDPR, CCPA, HIPAA, SOC 2, PCI-DSS coverage
- `auth` — WebAuthn/passkeys, TOTP 2FA, magic links, device-code flow
Licensed plugins are [source-available](https://nself.org/legal/bundle-license). License validated server-side via `ping.nself.org`. Revoked keys render plugins inert on next build.
---
## Companion Products
ɳSelf powers six open-source apps. Each is an MIT app you self-host:
| App | Bundle | Price | What it does |
|-----|--------|-------|-------------|
| [ɳTasks](https://github.com/nself-org/ntask) | Free | $0 | Task management — free, no paid plugins ever |
| [ɳChat](https://github.com/nself-org/nchat) | ɳChat | $0.99/mo | Messaging with live video, bots, and moderation |
| [ɳClaw](https://github.com/nself-org/nclaw) | ɳClaw | $0.99/mo | AI personal assistant with self-organizing memory |
| [ɳFamily](https://github.com/nself-org/nfamily) | ɳFamily | $0.99/mo | Private family social hub (planned) |
| [ɳSentry](https://github.com/nself-org/nsentry) | ɳSentry | $0.99/mo | Monitoring, status pages, and error tracking |
| [ClawDE](https://github.com/nself-org/clawde) | ClawDE | $0.99/mo | AI development environment (desktop + mobile) |
Each app's backend is powered by the nself CLI + the matching plugin bundle.
---
## Configuration
Config lives in `.env.dev` (team defaults), `.env.staging`, and `.env.prod`. `nself build` reads the active env file and generates `docker-compose.yml` and Nginx config.
Never hand-edit `docker-compose.yml` — it is generated and will be overwritten on the next build.
```bash
nself config show # show current config
nself config set KEY VALUE
nself config validate # validate before building
```
### Env file priority (low to high)
1. `.env.dev` — team defaults (checked in)
2. `.env.staging` — staging shared config (checked in)
3. `.env.prod` — production shared config (checked in)
4. `.env.secrets` — production secrets (not checked in)
5. `.env` — local overrides (not checked in, highest priority)
### Custom services (40+ templates)
Add your own services via `CS_N` slots:
```bash
CS_1=api:fastapi:3001 # Python FastAPI
CS_2=worker:bullmq-ts:3002 # TypeScript BullMQ
CS_3=grpc:grpc:3003 # gRPC service
```
Templates: JavaScript/TypeScript (19), Python (7), Go (4), Rust, Java, C#, Elixir, and more.
---
## Production Deployment
```bash
# Copy project to server
rsync -az --exclude .volumes/ ./ user@server:/opt/myapp/
# On the server
nself start --env prod
nself status
nself health check
```
Security hardening runs automatically on every deploy. No license required.
See [Self-hosting: what is and is not included](https://nself.org/docs/self-hosting/boundary) for
what nSelf provides vs. what you own as the operator (backups, monitoring, on-call, capacity).
---
## Requirements
| | Minimum | Recommended |
|---|---------|-------------|
| Docker | 24+ | latest |
| macOS | 12 (Monterey) | 14+ |
| Linux | Ubuntu 20.04 / Debian 11 | Ubuntu 22.04+ |
| RAM | 2 GB | 4 GB |
| Disk | 5 GB | 10 GB |
---
## Docs and Community
- [nself.org/docs](https://nself.org/docs) — complete documentation
- [nself.org](https://nself.org) — project home, pricing, plugins catalog
- [GitHub Discussions](https://github.com/nself-org/cli/discussions) — community Q&A
- [GitHub Issues](https://github.com/nself-org/cli/issues) — bug reports
---
## Contributing
The CLI is written in Go (1.22+). See [Contributing](.github/wiki/Contributing.md) for the full guide.
Quick setup:
```bash
git clone https://github.com/nself-org/cli
cd cli
make build # produces ./nself
make test # go test -mod=vendor ./...
```
Tests live in `internal/` alongside the packages they test. Coverage target: 70% on `cmd/commands/` and `internal/`. Integration tests gate on `INTEGRATION=1` and require Docker.
---
## License
MIT, free for personal and commercial use. See [LICENSE](LICENSE).
Licensed plugins (count generated from the bundles registry, not hand-typed here) are [source-available](https://nself.org/legal/bundle-license) under the nSelf Bundle License. Compiled binaries are distributed through `ping.nself.org` after license validation.
---
<div align="center">
**ɳSelf CLI v<!-- BEGIN GENERATED:facts:version -->1.4.15<!-- END GENERATED:facts:version -->** · [nself.org](https://nself.org) · [GitHub](https://github.com/nself-org/cli)
[Get Started](#quick-start) · [Documentation](https://nself.org/docs) · [Pricing](#pricing)
</div>