init

arkenv on npm is the CLI. It scaffolds schemas and wires framework config. Validation lives in @arkenv/core or @arkenv/standard. For the walkthrough, see Installation.

npx arkenv init

Usage

arkenv init [project-name] [options]

Omit project-name to mutate the current directory. Pass a name to create a new folder (optionally from --example).

Global flags (--yes, --quiet, --json, --agent, --help) apply here too.

Options

These flags are specific to init.

--force / -f

Bypass dirty-git and other safety checks, then force scaffolding. The CLI refuses a dirty working tree so a run cannot silently overwrite uncommitted work. Commit or stash first, or pass --force when you accept that risk (for example in CI).

--no-codegen

Skip Next.js env.gen.ts generation and related withArkEnv wiring.

--preset / -P

Pre-populate provider system variables. Values: none, vercel, netlify, cloudflare, railway, render, fly.

See Hosting presets.

--agent

Same macro as the global --agent flag: --yes --quiet --json. It does not imply --force.

When a safety check fails (dirty git tree), stdout is an errored settlement envelope (ok: false) and the process exits non-zero:

{
  "ok": false,
  "commandId": "init",
  "error": {
    "code": "CLI.GIT_TREE_DIRTY",
    "severity": "error",
    "summary": "Git working tree is not clean.",
    "why": "Commit or stash your changes before running arkenv init.",
    "nextActions": [
      {
        "kind": "run-command",
        "label": "Re-run with --force to bypass git working tree check",
        "command": "arkenv init --force"
      }
    ]
  },
  "diagnostics": [],
  "nextActions": [
    {
      "kind": "run-command",
      "label": "Re-run with --force to bypass git working tree check",
      "command": "arkenv init --force"
    }
  ]
}

Branch on error.code (dotted CLI.* / ENV.* codes). Use nextActions for remediation — a run-command action with --force means the refusal is bypassable. Only re-run with that flag after you confirm the bypass is safe. The same envelope shape is documented for check --json.

--example <name>

Scaffold from a named example when creating a new project. Short -e is reserved and rejected.

See Start with an example.

Output

Depending on the detected framework and flags, init writes:

• Schema file: env.ts (often under src/)
• .env / .env.example when missing. Init never reads an existing .env; a missing .env.example is scaffolded from detected keys and defaults. If .env is missing, init may copy .env.example into it.
• Next.js: withArkEnv in next.config.*, .arkenv/ in .gitignore, optional .arkenv/env.gen.ts (import as @/.arkenv)
• Vite / Bun / Rsbuild: plugin configuration in vite.config.* / bunfig.toml / rsbuild.config.*
• Dependency installs for the chosen dialect (@arkenv/core, plugins, Zod/Valibot)

init does not install the ArkEnv agent skill. On an existing project it checks whether the skill is already present. When it is not, the next-steps note prints the manual command. --yes and --agent do not run that command.

npx skills add yamcodes/arkenv

That install is separate from scaffolding. @arkenv/agent-plugin already includes the skill, so skip the command when the plugin is installed. See Agent skill.

Import the validator from core

The CLI package is not the validation library. Import arkenv() from @arkenv/core (or @arkenv/standard).

// Wrong: arkenv is the CLI package
import arkenv from "arkenv";

// Right
import arkenv from "@arkenv/core";

Importing arkenv as a library throws and points you at @arkenv/core.

Next steps