Skip to content

docs: simplify README for users #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nazarli-shabnam merged 1 commit into from
Jun 21, 2026
Merged

docs: simplify README for users #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 35 additions & 159 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,195 +1,71 @@
# envkit

**envkit** is a CLI that manages local development environments from a single config file. Define dependencies, databases, and services in one place; run one command to set up the project, generate Docker Compose, and optionally snapshot or share configs—without committing secrets.
Set up your whole local dev environment with one command. Define your dependencies, databases, and services in a single file — then let envkit install everything, spin up Docker, and keep your setup shareable and versioned. Secrets stay in `.env`, never in your config.

**Requirements:** Node.js >= 16

---

## What it does

- **Setup** — Uses your `.dev-env.yml` to install dependencies and run database migrations and seed commands in one go.
- **Generate** — Builds a `docker-compose.yml` from the same config (databases, services, network).
- **Snapshots** — Saves and restores config versions under `.devkit/snapshots/` so you can switch between setups.
- **Share** — Exports a sanitized config (secrets replaced with placeholders) or imports a shared config file into your project.

Configuration is a single YAML file; secrets live in `.env` and are referenced as `${VAR_NAME}`. The CLI discovers the project root from your current directory (it looks for `.dev-env.yml` or markers like `package.json`).

---
> Requires Node.js 16+

## Install

```bash
npm install -g dev-env-kit
```

After installation you can use either:

- **`envkit <command>`** — short name
- **`dev-env-kit <command>`** — same, using the package name

After install, **path-setup** runs automatically: if you're in an interactive terminal, you may be prompted to add envkit to your PATH so `envkit` works from any folder. You can run it again anytime with `npx dev-env-kit path-setup` or `npx dev-env-kit pathsetup` (no hyphen; use `pathsetup` if your shell doesn't like `path-setup`).

If the command is still not found, use:

```bash
npx dev-env-kit <command>
```

---

## How to use

### 1. Add a config file

You need a `.dev-env.yml` in your project root for **setup**, **generate**, **share export**, and **snapshot create**. If you don’t have one yet:

- **Interactive terminal:** Run `envkit init` to create `.dev-env.yml` via a short wizard. If you run a command that needs config (e.g. `envkit setup`) without a config file, the CLI will ask whether to run `envkit init` now.
- **Non-interactive (CI, scripts):** Create `.dev-env.yml` by hand or run `envkit init` in a terminal first; otherwise those commands exit with a message to create a config or run `envkit init`.

**If you already have an example file**, the fastest way to start is to copy it and edit it:

```bash
cp .dev-env.example.yml .dev-env.yml
```

The example file documents all options (dependencies, databases, services, env vars, Docker settings). Keep sensitive values in a `.env` file and reference them in the config with `${VAR_NAME}` so they never end up in version control.

See [.dev-env.example.yml](./.dev-env.example.yml) for the full reference.

### 2. Set up the environment

From the project root (or any subdirectory):

```bash
envkit setup
```

This installs dependencies, runs database migrations, and runs seed commands according to your config. You can narrow what runs:

| Option | Description |
|---------------|--------------------------------------|
| `--skip-deps` | Skip dependency installation |
| `--skip-db` | Skip database migrations and seed |
| `--dry-run` | Show what would run, without running |

### 3. Validate your config

Check that `.dev-env.yml` (and any `.env`) is well-formed without running setup or generate — handy for CI and pre-commit hooks:

```bash
envkit validate
```

It exits non-zero on a missing or invalid config. Add `--strict` to also fail on warnings (e.g. hardcoded passwords, port conflicts) and unresolved `${VAR}` references:

```bash
envkit validate --strict
```

### 4. Generate Docker Compose

When `docker.enabled` is set in your config, you can generate a Compose file from it:

```bash
envkit generate
```

Output goes to `docker-compose.yml` by default. Use `-o <file>` to write elsewhere, e.g. `envkit generate -o docker-compose.dev.yml`. To preview the generated Compose without writing a file (e.g. to pipe or inspect it), use `--dry-run`:

```bash
envkit generate --dry-run
```

### 5. Snapshots

Save the current config as a named snapshot under `.devkit/snapshots/`:

```bash
envkit snapshot create [name]
```

If you omit the name, a timestamp-based name is used. List existing snapshots:

```bash
envkit snapshot list
```
This gives you the `envkit` command (also available as `dev-env-kit`). If your shell can't find it afterward, run `envkit path-setup` once.

Restore a snapshot. This overwrites `.dev-env.yml`, but your current config is automatically backed up to a `pre-restore-<timestamp>` snapshot first, and you'll be asked to confirm in an interactive terminal (use `--yes` to skip the prompt in scripts):
## Quick start

```bash
envkit snapshot restore <name>
envkit init # answer a few questions to create .dev-env.yml
envkit setup # install dependencies + run migrations/seeds
envkit generate # create docker-compose.yml from your config
```

Delete a snapshot you no longer need:
That's the whole loop. Run any command from your project root or any subfolder — envkit finds the project automatically.

```bash
envkit snapshot delete <name>
```
## Commands

### 6. Share config (export / import)
| Command | What it does |
|---------|--------------|
| `envkit init` | Create your `.dev-env.yml` with a short interactive wizard. |
| `envkit setup` | Install dependencies and run database migrations + seeds. Skip parts with `--skip-deps`, `--skip-db`, or preview with `--dry-run`. |
| `envkit validate` | Check your config is valid — great for CI. Use `--strict` to also fail on warnings. |
| `envkit generate` | Build a `docker-compose.yml` from your config. `--dry-run` prints it instead of writing. |
| `envkit snapshot create/list/restore/delete` | Save and switch between config versions. Restoring backs up your current config first. |
| `envkit share export` / `import` | Share your setup with teammates — secrets are swapped for placeholders on export. |

Export a safe-to-share copy of your config (passwords and secrets become placeholders like `${DB_PASSWORD}`):
Add `-v` for more detail or `-q` for less. Run `envkit <command> --help` anytime.

```bash
envkit share export
```
## Configuration

By default this writes `dev-env.shared.yml`. Use `-o <file>` to change the path.
Everything lives in one `.dev-env.yml` at your project root. Keep secrets in a `.env` file and reference them with `${VAR_NAME}`:

Import a shared config file (it is validated and then written to `.dev-env.yml` by default). The `<file>` path is resolved relative to your **current working directory**:
```yaml
name: my-app

```bash
envkit share import path/to/dev-env.shared.yml
```
dependencies:
- type: npm
command: npm install

Use `-o <file>` to write to a different path (also relative to the current directory unless you pass an absolute path). To check a shared file is valid without writing anything (useful in CI), pass `--validate-only`:
databases:
- type: postgresql
port: 5432
user: ${DB_USER}
password: ${DB_PASSWORD}
database: myapp

```bash
envkit share import path/to/dev-env.shared.yml --validate-only
docker:
enabled: true
```

### Global options
See [.dev-env.example.yml](./.dev-env.example.yml) for every available option. Don't have a config yet? Just run `envkit init` — or if you run `envkit setup` without one, it'll offer to create it for you.

- **`-v, --verbose`** — More detailed log output.
- **`-q, --quiet`** — Reduce output.

Example: `envkit -q setup`

---

## Command reference

| Command | Description |
|--------|-------------|
| `envkit init` | Create `.dev-env.yml` interactively (wizard). Run from a project folder when you don’t have a config yet. |
| `envkit setup` | Install dependencies, run database migrations, and run seed commands from your config. Use `--skip-deps`, `--skip-db`, or `--dry-run` to limit what runs. |
| `envkit validate` | Validate `.dev-env.yml` (and `.env`) without running setup or generate. Add `--strict` to fail on warnings and unresolved `${VAR}` references. CI/pre-commit friendly. |
| `envkit generate` | Generate `docker-compose.yml` from your config (requires `docker.enabled` in config). Use `-o <file>` to set the output path, or `--dry-run` to print without writing. |
| `envkit snapshot create [name]` | Save the current `.dev-env.yml` as a snapshot under `.devkit/snapshots/`. Omit `name` to use a timestamp. |
| `envkit snapshot list` | List all saved snapshots. |
| `envkit snapshot restore <name>` | Restore a snapshot; overwrites `.dev-env.yml` (current config is backed up first). Use `--yes` to skip the confirmation prompt. |
| `envkit snapshot delete <name>` | Delete a saved snapshot. |
| `envkit share export` | Export a sanitized config (secrets → placeholders) to share safely. Default output: `dev-env.shared.yml`; use `-o <file>` to override. |
| `envkit share import <file>` | Import a shared config file; writes to `.dev-env.yml` by default. Use `-o <file>` to write elsewhere, or `--validate-only` to validate without writing. |
| `envkit path-setup` or `envkit pathsetup` | Add the npm global bin folder to your PATH so `envkit` works from any directory. Use if the shell says “envkit” is not recognized after a global install. |

For more detail: `envkit --help` or `envkit <command> --help`.
---

## Development and testing

To work on the source or run tests:
## Contributing

```bash
npm install
npm test
```

Use `npm test -- --coverage` for a coverage report.

---

## License

MIT
Loading