Installation
Install ArkEnv with the CLI or by hand in a new or existing project.
Prerequisites
- Node.js: Active or Maintenance LTS.
- Package manager: npm, pnpm, Yarn, or Bun (required for the interactive CLI).
ArkEnv is designed to drop into a new or existing TypeScript app. ArkEnv provides an interactive CLI that detects your stack, writes a schema, and wires framework config.
npx arkenv initOmit a project name to mutate the current directory. Pass a name to
create a new folder (optionally from --example):
npx arkenv init my-app --example with-vite-react --preset vercelFor agent sessions, use --agent (implies --yes --quiet --json):
npx arkenv init --agentLocal installation (recommended workflow)
Install the runtime validation engine as a dependency, and the arkenv CLI as a devDependency:
npm install @arkenv/core
npm install -D arkenvIf you are using Zod:
npm install @arkenv/standard zod
npm install -D arkenvIf you are using Valibot:
npm install @arkenv/standard valibot @valibot/to-json-schema
npm install -D arkenvWhy install locally?
- Deterministic versioning: Locks the exact CLI version in
package-lock.jsonorpnpm-lock.yaml, ensuring absolute consistency across team members and CI pipelines. - Zero latency & offline execution: Executions run instantly from
node_modules/.bin/arkenvwithout querying npm, working completely offline. - CI/CD reliability: Pipelines execute the version frozen in the lockfile instead of dynamically resolving
@latest.
Once installed locally, running npx arkenv <command> (or pnpm arkenv, bun arkenv) inside your project automatically executes your locked local binary from node_modules/.bin.
Wire into package.json scripts
Add arkenv check to your project scripts to validate environment variables before builds:
{
"scripts": {
"build": "arkenv check && next build",
"env:check": "arkenv check"
}
}Flags, output files, and refusal codes live in
init reference.
Add to an existing repository
When the CLI finds a package.json, it adopts the repo incrementally.
Run the interactive CLI
npx arkenv initThe CLI refuses a dirty git working tree. Commit or stash
(git stash -u) first, or pass
--force if you accept overwriting
generated files.
The CLI never reads your actual .env files. Suggested schema
key names come from .env.example if you have one, otherwise from
process.env / import.meta.env usage in source.
Answer the wizard
The CLI asks about framework, validator, and hosting preset.
If compilerOptions.strict is off in tsconfig.json, the wizard
offers to enable it (recommended).
Review generated files
After the CLI, a Next.js app (for example) looks like this:
If the project has a src/ directory, the schema lands at
src/env.ts instead.
Import env in your app
If you don't have a .env file yet, copy the example and fill in
values:
cp .env.example .envImport env instead of process.env (or import.meta.env):
import { } from "../env";
console.log(.DATABASE_URL);Manual installation
Prefer a hands-on setup? Install the validation engine yourself, then add a framework package from the framework guides.
Validation engine
@arkenv/core is the ArkType-powered engine.
arktype is a required peer.
npm install @arkenv/core arktypeIf you use Zod or Valibot, install
@arkenv/standard instead:
npm install @arkenv/standard zodnpm install @arkenv/standard valibot @valibot/to-json-schemaTypeScript module resolution
@arkenv/standard subpath exports (/valibot, /zod-mini) and the
framework plugin subpaths require modern TypeScript module resolution.
Set compilerOptions.moduleResolution to "bundler", "node16", or
"nodenext". Legacy "node" resolution is not supported.