one env

one env manages monorepo environment variables across environments. There are two backends:

• dotenv (default): local filesystem. Each project has overlays such as .env, .env.<env>, .env.local, and .env.<env>.local.
• infisical: one workspace shares one Infisical project; environments such as dev / preview / prod are sections inside that project.

For the full workflow and mental model, read Environment variables guide.

Environment Model

manifest.environments.names is the workspace environment list. one create defaults to ["dev","preview","prod"]. manifest.environments.default is the fallback when --env is omitted; default is dev. Existing workspaces that use staging remain valid; the Dashboard's Preview binding maps to staging when that legacy name is present and preview is not.

--env resolution:

--env flag -> manifest.environments.default -> environments.names[0]

one env set FOO bar --env qa can create a new environment. TTY mode asks for confirmation; non-TTY / --yes appends directly to manifest.environments.names. get, list, and pull are read-only: unknown env names return ENV_UNKNOWN_ENVIRONMENT.

Usage

one env set  <KEY[=VALUE]> [VALUE] [--env <env>] [-p <name|path>] [--yes]
one env get  <KEY>                 [--env <env>] [-p <name|path>] --reveal
one env list                       [--env <env>] [-p <name|path>]
one env pull                       [--env <env>] [-p <name|path>] [--force] [--dry-run]

-p / --project accepts a manifest project name or workspace-relative path:

one env set FOO=bar -p web
one env set FOO=bar -p apps/web
one env set FOO=bar              # auto-detects project from cwd
one env pull -p api              # only pull api
one env pull --env staging       # pull staging vars for all projects

The global output flag is -o / --output, with json, yaml, or text.

There is no one env init subcommand today. Infisical project binding is attempted by one create --env-provider infisical. If login, network, or permissions were not ready during create, the first set/get/list/pull retries lazy auto-bind.

Machine-level Infisical credentials are configured with one login. They do not go into the manifest.

Interactive Mode

Bare one env shows the current source, default/available environments, current scope, and common commands. one env set has a safe TTY flow:

• one env set KEY reads the value with hidden input.
• At the workspace root, it asks whether the variable is shared or belongs to a project.
• When writing to an environment that is not in manifest.environments.names, it asks whether to add that environment to the manifest.
• When overwriting an existing different value, it asks whether to overwrite.

Declining or cancelling exits successfully without an error-style message. Scripts and CI pass the value explicitly and use --yes for overwrite/new-environment confirmation.

dotenv Overlay

The dotenv backend reads files in this order:

<project>/.env
<project>/.env.<env>
<project>/.env.local
<project>/.env.<env>.local

Later files override earlier files. one env set writes .env.<env>; .local files are read-only from One CLI's perspective and are maintained by developers.

one create writes this to .gitignore by default:

.env
.env.*
!.env.example

set

Write one key. Both argument forms work:

one env set DATABASE_URL "postgres://localhost/dev" --env dev -p api
one env set JWT_SECRET=dev-only-secret --env dev -p api --yes

Output schema: one-cli/env-set/v1

{
  "schema": "one-cli/env-set/v1",
  "env": "dev",
  "key": "DATABASE_URL",
  "action": "created"
}

action can be created, updated, or unchanged. Existing different values require --yes to confirm overwrite.

get

Read one key:

one env get DATABASE_URL --env dev -p api --reveal
DB_URL=$(one env get DATABASE_URL --env dev -p api -o json | jq -r .value) --reveal

Output schema: one-cli/env-get/v1

{
  "schema": "one-cli/env-get/v1",
  "env": "dev",
  "key": "DATABASE_URL",
  "value": "postgres://..."
}

list

List key names without values:

one env list --env dev -p api

Output schema: one-cli/env-list/v1

{
  "schema": "one-cli/env-list/v1",
  "env": "dev",
  "keys": ["DATABASE_URL", "JWT_SECRET"]
}

pull

Pull Infisical variables into local .env:

one env pull --env dev
one env pull --env dev -p api --dry-run
one env pull --env dev --force

Without -p, One CLI iterates through manifest.projects[]. Each project maps to an Infisical folder from projects[].domains.env.path or relativeDir, merges root -> ancestors -> self inheritance, and writes the resulting .env into that project directory.

Output schema: one-cli/env-pull/v1

{
  "schema": "one-cli/env-pull/v1",
  "env": "dev",
  "dry_run": false,
  "written_count": 1,
  "skipped_count": 0,
  "per_subproject": [
    {
      "name": "api",
      "relative_dir": "services/api",
      "infisical_path": "/services/api",
      "env_file_path": "/abs/.../services/api/.env",
      "status": "written",
      "keys_written": ["DATABASE_URL", "JWT_SECRET"]
    }
  ]
}

Manifest Configuration

Workspace env backend lives in one.manifest.json#domains.env; environments live at top-level environments:

{
  "environments": {
    "names": ["dev", "staging", "prod"],
    "default": "dev"
  },
  "domains": {
    "env": {
      "kind": "infisical",
      "config": {
        "siteUrl": "https://app.infisical.com",
        "projectId": "...",
        "projectName": "my-workspace",
        "rootPath": "/"
      }
    }
  }
}

Project path overrides live in projects[].domains.env:

{
  "projects": [
    {
      "name": "charge",
      "relativeDir": "services/charge",
      "domains": {
        "env": {
          "path": "/teams/payments/charge",
          "inherits": true
        }
      }
    }
  ]
}

Values never enter the Manifest. It records project identity, instance URL, folder paths, and key names. Authentication uses the single browser session in the system keyring.

Credential Safety

Use one login; the token lives only in the system keyring, outside project and ordinary configuration files.

Common Errors

Code	Recovery
INFISICAL_NOT_CONFIGURED	Confirm the workspace uses --env-provider infisical and you have signed in with one login
INFISICAL_AUTH_MISSING	Re-run one login
INFISICAL_AUTH_FAILED	Regenerate the client secret in Infisical
INFISICAL_PROJECT_NAME_TAKEN	Change domains.env.config.projectName and rerun an env command to trigger lazy bind
INFISICAL_PROJECT_CREATE_FORBIDDEN	Grant admin role to the machine identity, or manually create the project and fill domains.env.config.projectId
ENV_PULL_CONFLICT	Local .env exists and differs; add --force after confirming overwrite
ENV_KEY_NOT_FOUND	Check path, env name, and spelling
ENV_INVALID_KEY	Keys must match ^[A-Za-z_][A-Za-z0-9_]*$
ENV_SET_OVERWRITE_REQUIRED	Existing value differs; add --yes to confirm
ENV_UNKNOWN_ENVIRONMENT	set can create; read commands require the env to exist in manifest.environments.names

Full table: Error codes.

Next

• Environment variables guide — mental model and complete workflow
• one create — use --env-provider infisical during workspace creation

Shared credentials

Shared credentials are independent of workspaces. Select storage with one env bind --global, browse metadata with one env list --global --env dev --path /, and inject an explicit scope with one run --global --env dev --path /folder -- command. See login and shared credentials for commands and security boundaries.