<!-- GENERATED BY tools/wikigen — DO NOT HAND EDIT (PROSE blocks excepted) -->
# nself init

<!-- BEGIN PROSE:summary -->
> Initialize a new ɳSelf project. It asks no questions: `nself init && nself start` works with zero prompts.
<!-- END PROSE:summary -->

## Synopsis

<!-- BEGIN GENERATED:synopsis -->
<!-- GENERATED BY tools/wikigen — DO NOT HAND EDIT -->
```
nself init <subcommand> [flags]
```
<!-- END GENERATED:synopsis -->

## Description

<!-- BEGIN PROSE:description -->
`nself init` launches an interactive setup wizard that creates a pristine `.env` configuration for a new ɳSelf project. It uses the project directory name and the default base domain `local.nself.org` (override with `--name` and `--domain`), then auto-generates cryptographically secure secrets (Postgres password, Hasura admin secret, JWT key).

You can choose which optional services to enable during init (Redis, MinIO, MeiliSearch, Mailpit, Monitoring). Each selection updates the generated `.env` accordingly. All values are validated before being written, domain format, password strength, and required fields are all checked.

After `nself init` completes, run `nself build` to generate `docker-compose.yml` and nginx configs, then `nself start` to boot the stack.

## Derived project and database names

`init` takes the project name from the current directory name and writes it to
`PROJECT_NAME`. It also derives `POSTGRES_DB` from that name, because a
database name has to be a valid SQL identifier and a directory name frequently
is not.

The derivation lowercases the name, folds `-`, `.` and space to `_`, drops
anything else, prefixes a leading digit with `_`, and truncates to Postgres's
63-byte identifier limit. So `my-app` yields database `my_app`, while
`PROJECT_NAME` keeps its hyphens for Docker compatibility. The two values are
allowed to differ and normally do.

Set `POSTGRES_DB` yourself in `.env` if you want a specific name. A directory
name that reduces to nothing usable (`---`, for example) is rejected at init
rather than at first start.

## Clone Templates

Clone templates are full-stack app starters embedded in the CLI binary. They include a Postgres schema with RLS policies, Hasura metadata, seed data, and a Flutter UI starter. The files are embedded, so scaffolding downloads nothing; the plugin check below reads the plugin catalog (the cached copy works offline).

### Available clone templates

| Template | Tables | Required plugins |
|---|---|---|
| `airbnb-clone` | `np_listings`, `np_bookings`, `np_reviews` | `auth`, `notify`, `photos` |
| `discord-clone` | `np_servers`, `np_channels`, `np_messages`, `np_members`, `np_roles` | `chat`, `realtime`, `auth`, `moderation` |
| `notion-clone` | `np_workspaces`, `np_pages`, `np_blocks`, `np_page_members` | `cms`, `auth`, `realtime` |
| `slack-clone` | `np_workspaces`, `np_channels`, `np_messages`, `np_threads`, `np_reactions` | `chat`, `livekit`, `realtime`, `auth`, `notify` |
| `substack-clone` | `np_newsletters`, `np_posts`, `np_subscribers`, `np_tiers` | `cms`, `notify`, `auth` |
| `zoom-clone` | `np_meetings`, `np_participants`, `np_recordings` | `livekit`, `recording`, `auth`, `notify` |

### Plugin entitlement

Before it writes anything, `nself init --template <x>-clone` looks up each required plugin in the plugin catalog and checks your licence against the Bundles that include the licensed ones. A template whose plugins are all free makes no licence call.

| Finding | From v1.5 | In v1.4 mode |
|---|---|---|
| A licensed plugin your licence does not cover | Refused with `E110` (exit 3); the message lists each plugin, the Bundles that include it and the purchase link. Nothing is written. | The same text is printed as a warning and the template is scaffolded. |
| A plugin that is in no registry (`recording`, required by `zoom-clone`) | Refused with `E137` (exit 1). | Warning, then scaffold. |
| No catalog and no cached copy | Refused with `E115` (exit 2). | Scaffold, no message. |

A licensed plugin is covered when any of your configured licence keys covers one of its Bundles (an all-access licence such as ɳSelf+ covers them all). A licensed plugin that is in no Bundle cannot be decided here; init prints a note and `nself plugin install` checks it later. A plugin that exists in both tiers counts as free, as it does for `nself plugin install` without a licence. In v1.4 mode the whole check gives up after 8 seconds, so a slow network never holds up the scaffold, and a check that timed out prints nothing. Init may print a `note:` line for licensed plugins that are in no Bundle, and the licence client's offline-grace warning when the licence server is unreachable. Buy a Bundle at https://nself.org/pricing or run `nself license set <key>`, then run the command again.

### Usage

```bash
# Scaffold a clone template into the current directory
nself init --template airbnb-clone

# Scaffold into a named directory
nself init --template discord-clone ./my-discord

# Skip seed data (schema only)
nself init --template notion-clone --no-seed

# Preview files without writing
nself init --template slack-clone --dry-run

# Scaffold and immediately install required plugins
nself init --template substack-clone ./my-newsletter
cd my-newsletter
nself plugin install cms notify auth
nself start
nself db migrate
nself hasura metadata apply --file hasura/metadata.json
```

### What gets scaffolded

Each clone template writes:

```
<dest>/
  migrations/
    001_schema.sql   — CREATE TABLE np_* statements with RLS policies
    002_seed.sql     — demo data (omitted with --no-seed)
  hasura/
    metadata.json    — Hasura permissions and relationships
  flutter/
    pubspec.yaml
    lib/main.dart    — starter app with GraphQL client and skeleton screens
  nself.yml          — project config with required plugins list
  .env.example       — environment variable template
  README.md          — getting started guide
```

Use `nself template list` to see all bundled and marketplace templates together.

## Telemetry

`nself init` emits a single anonymous `init_complete` event when `NSELF_TELEMETRY_OPT_IN=1` is set. The event is sent in a background goroutine with a 1-second timeout and is silently dropped on failure.

**Opt-in only.** No data is collected unless you explicitly set the environment variable. Absence of the variable means zero network calls.

Fields collected:

| Field | Type | Example | Notes |
|---|---|---|---|
| `wizard_mode` | string | `fast`, `wizard`, `demo`, `non-interactive`, `default` | Which init mode was used |
| `duration_ms` | integer | `312` | Time from command start to completion |
| `success` | bool | `true` | Whether init completed without error |
| `err_category` | string | `docker-not-found` | Error bucket; one of `timeout`, `permission-denied`, `docker-not-found`, `other` |
| `install_source` | string | `hn` | Source tag from `?ref=` in install.sh (nullable) |
| `install_method` | string | `brew` | How nself was installed: `brew`, `curl`, `docker`, `other` (nullable) |
| `app_context` | string | `nclaw` | Which Type-C app initiated this install (nullable) |

**No PII is collected.** Email addresses, file paths, project names, and license keys are never included. All values are categorical or numeric.

To opt in:

```bash
export NSELF_TELEMETRY_OPT_IN=1
nself init --fast
```
<!-- END PROSE:description -->

## Flags

<!-- BEGIN GENERATED:flags -->
<!-- GENERATED BY tools/wikigen — DO NOT HAND EDIT -->
| Name | Shorthand | Type | Default | Env | Escalates to | JSON override | Description |
|---|---|---|---|---|---|---|---|
| `--cs-template` |  | `string` | `""` |  |  |  | Scaffold a custom service at init time: specify language (go, node, python, rust, other) |
| `--demo` |  | `bool` | `false` |  |  |  | Auto-configure with all services enabled |
| `--domain` |  | `string` | `""` | `BASE_DOMAIN` |  |  | Base domain (default: local.nself.org; init never prompts for it, e.g. myapp.dev) |
| `--dry-run` |  | `bool` | `false` |  |  |  | Print files that would be written without writing them (clone templates only) |
| `--fast` |  | `bool` | `false` |  |  |  | Skip advanced options, use smart defaults |
| `--force` |  | `bool` | `false` |  |  |  | Overwrite existing configuration |
| `--full` |  | `bool` | `false` |  |  |  | Create all environment files (.env.dev, .env.staging, .env.prod, .env.secrets) |
| `--interactive` |  | `bool` | `false` |  |  |  | Explicitly enable interactive wizard |
| `--list-presets` |  | `bool` | `false` |  |  |  | List all available project presets and exit |
| `--name` |  | `string` | `""` |  |  |  | Project name (sets PROJECT_NAME in generated .env) |
| `--no-pgvector` |  | `bool` | `false` |  |  |  | Skip pgvector extension and RAG scaffold tables (sets PGVECTOR_ENABLED=false) |
| `--no-seed` |  | `bool` | `false` |  |  |  | Skip seed data when scaffolding a clone template |
| `--non-interactive` |  | `bool` | `false` |  |  |  | Use all defaults without prompts |
| `--preset` |  | `string` | `""` |  |  |  | Use a project-type preset: b2b-saas, mobile-backend, ai-assistant, community-forum, media-hosting, dev, sentry, nclaw-app |
| `--profile` |  | `string` | `""` |  |  |  | Resource profile: 'tiny' for small VPS (Postgres+nginx only) |
| `--quiet` |  | `bool` | `false` |  |  |  | Suppress output messages |
| `--skip-validation` |  | `bool` | `false` |  |  |  | Skip configuration validation |
| `--template` |  | `string` | `""` |  |  |  | Use a built-in, clone, or marketplace template (e.g. airbnb-clone, go, rust) |
| `--wizard` |  | `bool` | `false` |  |  |  | Run the full 10-step interactive wizard |
| `--help` | `-h` | `bool` | `false` | | | | Show help |
<!-- END GENERATED:flags -->

## Subcommands

<!-- BEGIN GENERATED:subcommands -->
<!-- GENERATED BY tools/wikigen — DO NOT HAND EDIT -->
| Name | Description |
|---|---|
| `template` | Browse and publish full-stack app templates |
<!-- END GENERATED:subcommands -->

## Contract

<!-- BEGIN GENERATED:contract -->
<!-- GENERATED BY tools/wikigen — DO NOT HAND EDIT -->
- **Side effect:** `write`
- **Output:** `document`
- **JSON:** `envelope` ([data schema](https://github.com/nself-org/cli/blob/main/schemas/commands/init.v1.schema.json))
- **Exit codes:** none declared
<!-- END GENERATED:contract -->

## Examples

<!-- BEGIN PROSE:examples -->
```bash
# Minimal interactive setup
nself init

# Full 10-step wizard
nself init --wizard

# All services enabled (demo/evaluation)
nself init --demo

# Create all env files at once
nself init --full

# Smart defaults, no prompts
nself init --fast

# Non-interactive — all defaults, safe for CI
nself init --non-interactive

# Small VPS (512 MB–1 GB RAM): start with Postgres + nginx only
nself init --profile=tiny

# Skip prompts by supplying name and domain directly
nself init --name myapp --domain myapp.dev

# Start from a Go project template
nself init --template go --name myapi --domain myapi.local
```
<!-- END PROSE:examples -->

## See Also

<!-- BEGIN PROSE:see-also -->
- [[Commands]] — full command index
- [[Core-Services]] — what a stack is made of
<!-- END PROSE:see-also -->

← [[Commands]] | [[Home]] →