Infisical CLI

Infisical CLI

Practical guide to driving Infisical from the command line. Always confirm with the user before any destructive operation (secrets delete, secrets folders delete, reset, bootstrap against a populated instance).

When to read which reference

Always read the reference for the operation at hand before issuing commands — flag semantics differ between subcommands (e.g., --type defaults to shared for set but personal for delete).

Installation check

Before running any command, verify the CLI is available:

!infisical --version 2>&1 || echo "infisical not installed; run: npm install -g @infisical/cli"

If missing, install: npm install -g @infisical/cli. Other installers (Homebrew, Scoop, Winget, apt/yum) are documented at https://infisical.com/docs/cli/overview.

Windows note: on git-bash / MSYS the npm-installed infisical shim may fail with Permission denied. Use PowerShell, or invoke infisical.exe directly. The infisical.ps1 shim in %APPDATA%\npm\ works from PowerShell.

Core mental model

1. Login produces a token cached in the OS keychain (vault). For interactive use, infisical login is enough; for CI/automation, use universal-auth and export INFISICAL_TOKEN.
2. infisical init writes .infisical.json linking the current folder to a workspace + default environment. Most subsequent commands read this file. Commit .infisical.json to the repo.
3. Secrets live at (environment, path) — e.g., prod env, /database path. --env (default dev) and --path (default /) appear on nearly every command.
4. infisical run -- <cmd> is the primary integration point: it fetches secrets, injects them as env vars, and execs your process. Prefer this over export to disk.
5. Self-hosted users must pass --domain https://your-host/api or set INFISICAL_API_URL once. Once you log in with --domain, it's remembered per profile.

Common workflows

First-time setup for a repo

cd path/to/repo
infisical login                    # interactive; pick org, opens browser
infisical init                     # pick workspace + default env; writes .infisical.json
git add .infisical.json && git commit -m "Link repo to Infisical workspace"

Run an app with injected secrets

infisical run --env=dev -- npm run dev
infisical run --env=prod --path=/api -- ./server
infisical run --command "migrate && start"     # chained shell commands

Read / write / delete a secret

infisical secrets                              # list dev secrets at /
infisical secrets --env=prod --path=/database  # list prod secrets at /database
infisical secrets get DATABASE_URL --plain     # value only
infisical secrets set DATABASE_URL=postgres://... API_KEY=abc
infisical secrets delete OLD_KEY --type shared # default --type for delete is "personal"

See references/secrets-operations.md for --file, @/path/to/file, tags, recursion, output formats.

Export to a file

infisical export --env=prod --format=dotenv > .env.prod
infisical export --env=prod --format=json -o secrets.json
infisical export --env=prod --template=./template.tmpl

CI / machine identity

export INFISICAL_TOKEN=$(infisical login \
  --method=universal-auth \
  --client-id="$INFISICAL_CLIENT_ID" \
  --client-secret="$INFISICAL_CLIENT_SECRET" \
  --plain --silent)

infisical secrets --projectId=<id> --env=prod
infisical run --projectId=<id> --env=prod -- ./deploy.sh

INFISICAL_UNIVERSAL_AUTH_CLIENT_ID / INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET env vars are also picked up — see references/authentication.md.

Self-hosted endpoint

export INFISICAL_API_URL=https://infisical.homelab.example/api
infisical login                    # remembers --domain for this profile
# OR per-command:
infisical secrets --domain=https://infisical.homelab.example/api --env=dev

Pre-commit secret scanning

infisical scan                                 # scan git history
infisical scan git-changes                     # scan only uncommitted changes
infisical scan --no-git --source ./dir         # scan plain directory
infisical scan install pre-commit              # set up a pre-commit hook

Project creation

Creating new projects is not a CLI operation — Infisical projects are created via the web UI or API. The CLI can:

• Link an existing project to a folder: infisical init
• Bootstrap a brand-new self-hosted instance (organization + admin): infisical bootstrap (see references/advanced.md)
• Issue credentials for an existing project: infisical service-token create, infisical login --method=universal-auth

If the user asks "create a project", clarify whether they mean (a) link this repo to an existing workspace (init), (b) bootstrap a new self-hosted instance (bootstrap), or (c) actually create a workspace inside an existing instance (web UI / API — point them to https://infisical.com/docs/api-reference).

Top-level command map

Safety rules

1. Never paste a --client-secret or service token into the conversation transcript. Read from an env var or a file the user controls.
2. Confirm before any delete / reset / bootstrap --ignore-if-bootstrapped.
3. Check git status before infisical export — never commit an exported secrets file. Add .env* patterns to .gitignore before exporting.
4. secrets set writes to remote immediately. There is no staging. Verify --env and --path before running.
5. secrets delete defaults to --type personal, not shared. Pass --type shared to delete the team-wide secret.
6. For self-hosted with custom CA, set INFISICAL_API_URL and ensure the cert chain is trusted by the OS, or curl will fail before infisical ever sees it.

Error patterns to recognize

• unauthorized / token expired → re-run infisical login, or infisical token renew <token> for universal-auth
• project not found → .infisical.json missing or --projectId wrong; run infisical init or pass --projectId
• environment "xxx" not found → env slug mismatch; check the workspace's actual env slugs in the UI (dev/staging/prod are conventions, not guarantees)
• secret already exists on set → set is upsert; this typically means a permissions issue
• permission denied on secrets ... → token scope too narrow; check the service token's --scope or machine identity's role