How to Use Infisical: The Beginner's Guide (First CLI Install, First Project, the No-.env Rule, and the Machine-Identity Lesson)

How to Use Infisical: The Beginner's Guide

If your project is held together by a pile of .env files you are afraid to open, Infisical is the upgrade path. It is an open-source secrets management platform — an encrypted vault for API keys, database credentials, and tokens — that injects secrets into your app as environment variables, so your code never has to change. This Infisical tutorial walks you through the full arc: installing the Infisical CLI, logging in, creating your first project, running your app with infisical run, self-hosting with Docker, and the machine-identity lesson that makes CI/CD safe. All examples use placeholder values only — never paste a real key into any command or file below.

What is Infisical?

Infisical is an open-source secrets management platform for developers and AI agents. Instead of scattering credentials across .env files on laptops, servers, and CI runners, Infisical stores them in one encrypted vault with a dashboard, a CLI, SDKs, a REST API, and native integrations. Your application reads the same environment variables it always has — process.env in Node.js, os.environ in Python — because the CLI injects the secrets at runtime. The core platform is open source and can be self-hosted on your own infrastructure, while Infisical Cloud is the managed option with US and EU regions. It authenticates machines, engineers, and agents to infrastructure — it is not a consumer password manager, and it is not meant to authenticate your app's end users.

Why teams switch from .env files (and when Vault is overkill)

The .env file starts as a convenience and ends as a liability: it gets committed to git by accident, screenshotted in Slack, copied to five servers with five different values, and rotated by nobody. A secrets manager fixes the root cause — there is one source of truth, access is audited, and rotation happens in one place. Teams reach for Infisical over HashiCorp Vault for the same reason they reach for a managed database over a self-built one: Vault is powerful but takes hours of configuration to run properly, while Infisical's own community describes a five-minute setup with a dashboard designed for developers rather than operators. That does not make Vault wrong — it makes it the wrong starting point for a team that just wants secrets out of .env files today. If you plan to run Infisical yourself, you will want a server to put it on — start with our what is VPS hosting explainer to pick the right size, since the managed Cloud version exists for everyone else.

How do I install the Infisical CLI?

Everything in this guide starts at the CLI. Install it with your operating system's package manager — on macOS that is one command:

brew install infisical/get-cli/infisical
infisical --version

Confirm the install with infisical --version before moving on. If you install the CLI on a server or bake it into a container image, pin a specific version so every reinstall gets the same one — the CLI releases list on GitHub shows every version. One freshness note for Linux users: the CLI's Linux package repository moved off Cloudsmith on September 16, 2026 and now lives on Infisical's own host, artifacts-cli.infisical.com. Machines still pointed at the old Cloudsmith source cannot install or upgrade the CLI, and on Debian/Ubuntu a dead source can even fail apt-get update for all packages — so if an older Linux box refuses to install, migrate the repository source first. Homebrew and Windows users are unaffected.

How do I log in to Infisical for the first time?

Run infisical login. The prompt asks which instance you want to use — Infisical Cloud (US Region), Infisical Cloud (EU Region), or a self-hosted or dedicated instance — then you finish signing in through your browser. The CLI saves the instance with your login, so later commands use it without asking again. Then verify the login works:

infisical login

When the CLI asks whether your login is valid, the output starts with the account or machine identity you are logged in as, followed by the instance it connected to. The lines after Domain tell you when the login expires and which organization it belongs to. If it says you are not authenticated, log in again; if it fails, check the Domain line is pointing at your instance.

There are two login shapes, and mixing them up is the most common beginner error. Log in with your own account when you run the CLI yourself — on your laptop during local development. Log in as a machine identity when the CLI runs without you — in a CI/CD pipeline, a container, a scheduled job, or a script on a shared server. The rest of this guide uses your personal login; the machine-identity section below covers automation.

How do I create my first project and add a secret?

Sign into the dashboard and create a project. Projects hold environments — typically dev, staging, and prod — and each environment holds key-value secrets. Add your first secret from the CLI:

infisical secrets set DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
infisical secrets set STRIPE_API_KEY="sk_test_placeholder" --env=prod
infisical secrets

The values above are placeholders — use your real values in the dashboard, never paste real keys into chat logs, scripts, or documentation. infisical secrets lists everything in your current environment, and the --env flag targets a specific one. This is the shape of the whole system: one project, several environments, and the CLI as the lens you look through.

Next, link your codebase to the project. In your project's directory, run the init flow and select your organization and project when prompted. The CLI writes an .infisical.yaml file with your local project settings, so later commands know which project you mean without needing a project ID every time. Commit this file — it contains no secrets, only pointers.

How do I run my app with secrets injected?

This is the heart of Infisical: start your application through infisical run (current docs name the command infisical sm run), and the CLI fetches the secrets you have access to and passes them to your app as environment variables:

infisical sm run -- npm start
infisical sm run -- python app.py
infisical sm run --env=prod -- ./start.sh

Your app reads them exactly as before — process.env.DATABASE_URL, os.environ["STRIPE_API_KEY"] — so you do not change any application code. Secrets stay in the process's memory; nothing is written to disk, which is precisely why this is safer than a .env file sitting in your repo directory. Two details that save beginners real time: if your start command is a shell function or alias rather than a binary, call it with --command (for example --command="npm run migrate && npm run dev"), and if one developer needs a different value on their own machine — say, a database URL pointing at localhost — they create a personal override instead of editing the shared secret. Their next run uses the override while the team keeps the shared value.

Before trusting a run, check what the CLI would inject. Listing the secrets for the environment shows every key your app will receive, which is the fastest way to diagnose an app that "behaves as though a value is missing" — it almost always turns out the key lives in a different environment than the one you ran with.

Your first 7 steps, in order

If you searched "how to use Infisical" looking for the ordered checklist rather than the concepts, this is the section you came for — the complete Infisical for beginners path, nothing skipped:

1. Install the CLI with your package manager and verify with infisical --version.
2. Log in with infisical login, picking Cloud (US/EU) or your self-hosted instance.
3. Create a project in the dashboard — it gets dev, staging, and prod environments.
4. Add your first secret with infisical secrets set KEY="placeholder-value".
5. Link your codebase to the project so the CLI writes .infisical.yaml.
6. Run your app with infisical sm run -- npm start and confirm it reads the secret from the environment.
7. Delete the .env file from the project — and add it to .gitignore if it is not there already.

What are machine identities (and when do I need one)?

A machine identity is a non-human credential for automation: the thing that logs in when there is no browser and no person, such as a CI runner, a production container, or a cron job. The official rule is simple — log in with your own account when you run the CLI, and log in as a machine identity when the CLI runs without you. Create one under Access Control > Machine Identities in your organization dashboard. By default an identity is configured with Universal Auth: it gets a client ID and a client secret, which the CLI reads from environment variables:

export INFISICAL_CLIENT_ID="<your-client-id>"
export INFISICAL_CLIENT_SECRET="<your-client-secret>"
infisical login --method=universal-auth

Treat the client secret like any secret — it lives in environment variables or a secret store, never in files or git. One community-tested hardening note: check the identity's access-token TTL and the client secret's TTL, and scope the identity to the narrowest project role (Viewer, not Admin) that still works. Short-lived tokens for CI jobs beat 30-day defaults.

How do I use Infisical in GitHub Actions?

The Infisical GitHub Actions story is really about one idea: your workflow should pull secrets at runtime instead of storing them. The official path is the Infisical Secrets Action (Infisical/secrets-action@v1): it authenticates as a machine identity, fetches the secrets that identity may read, and injects them into the job as environment variables that exist only for the job's lifetime — so you never copy secrets into GitHub Secrets or keep the two in sync. You have two authentication choices:

• OIDC (recommended). GitHub issues a short-lived token describing the repository and workflow at runtime; Infisical verifies its signature against the issuer https://token.actions.githubusercontent.com and checks the claims against your machine identity. No Infisical credential is stored in GitHub at all — nothing to rotate, nothing to leak.
• Universal Auth. The workflow authenticates with a client ID and client secret stored in GitHub Secrets, and Infisical returns a short-lived access token. Use it only when OIDC is not an option, and rotate the stored secret periodically.

Either way, store the machine identity ID and project slug as repository variables (not secrets — they are identifiers, not credentials), set env-slug to the environment you want (dev, staging, prod), and the action handles the rest. If you are automating deployments from Actions onto your own servers, pair this with our Docker beginner guide so the container the workflow ships can itself fetch secrets the same way.

How do I self-host Infisical with Docker?

The Infisical self-host story has two tiers. Self-hosting keeps all secret data on your own infrastructure — the usual reasons are compliance (the docs name SOC 2, HIPAA, and FIPS 140-3) and control over topology and networking. The quickest route is Docker: a single packaged container for trying it out, or the Docker Compose template that runs Infisical alongside PostgreSQL and Redis for real use. For a first Infisical Docker run, the single container gets the dashboard up in minutes; the Compose template is what you move to when a team depends on it. The Compose setup needs a Postgres database (community guides use POSTGRES_DB=infisical as the convention) and exposes the web dashboard, where you create the admin account on first launch. Beyond Compose there are official paths for Kubernetes (Helm chart with bundled PostgreSQL and Redis), a Linux package, and AWS/GCP reference architectures — and an upgrade guide for moving between versions without losing data. Whatever route you take, give the instance real resources and a proper domain with TLS before a team depends on it. Our Docker beginner guide covers the Compose mechanics if you are new to containers.

How do I sync secrets into Kubernetes?

Kubernetes workloads usually cannot call infisical run, so Infisical offers two Kubernetes-native patterns. Secret syncs push secrets from Infisical out to platforms that need their own copy — Kubernetes, AWS Secrets Manager, Vercel, GitHub Actions — and keep the destination current as values change; syncs are outbound only. Alternatively, the External Secrets Operator pulls: you install ESO in the cluster and define which Infisical paths map to which Kubernetes Secrets, so pods consume secrets the standard way. The sync path is simpler for a first cluster, while ESO fits teams already standardized on the operator pattern. Either way, the cluster nodes themselves run on something — our K3s beginner guide is the lightweight way to get that cluster.

Infisical vs HashiCorp Vault: which should I pick?

This is the comparison every beginner asks for, and in the Infisical vs Vault debate the deciding question is not "which is better" but "which problem do you have today." The honest answer is that they solve the same core problem at very different complexity budgets:

Start with Infisical when the problem is "secrets are scattered and nobody rotates them." Graduate to Vault when the problem becomes "we need credentials that are minted per-request and expire automatically." Many teams run Infisical for years before the second problem appears.

7 beginner mistakes (and the fix for each)

When should I export secrets to a file instead?

Some tools read secrets from a file and offer no way to accept them from the environment — legacy deploy scripts and certain config formats are the usual suspects. For those cases only, write the secrets out with infisical sm export. The official docs frame this exactly right: it is the escape hatch, not the default. Call it the no-.env rule: if a value lives in a file on disk, the migration is not done — every export recreates the .env problem you just solved, so keep exported files out of git, out of backups you do not control, and delete them when the tool that needed them is done.

One more guardrail for the same reason: install the pre-commit hook that scans your staged changes on every commit. Fetching secrets from Infisical keeps them out of the repository, but a credential can still reach a commit by being pasted into a source file — the hook stops the commit when it finds something that looks like a secret.

Sources

• Infisical official docs — "CLI quickstart" (install → log in → verify login; personal login vs machine identity; instance choice Cloud US/EU or self-hosted; login-expiry/Domain output), crawled 2026-10-31 — https://infisical.com/docs/cli/usage
• Infisical official docs — "Install the CLI" (brew install command; infisical --version; pin versions in production; Cloudsmith repository moved to artifacts-cli.infisical.com on 2026-09-16), crawled 2026-10-31 — https://infisical.com/docs/cli/install
• Infisical official docs — "Migrate off Cloudsmith" (S3 via CloudFront; who is affected: apt/yum/apk Linux installs, CI pipelines, container images; Homebrew/Windows unaffected), crawled 2026-10-31 — https://infisical.com/docs/cli/cloudsmith-migration
• Infisical official docs — "Inject secrets into local development" (infisical sm run; .infisical.yaml linking; no code changes, process.env/os.environ; --command for shell functions; personal overrides; infisical sm export as escape hatch; pre-commit secret scanning), crawled 2026-10-31 — https://infisical.com/docs/documentation/guides/local-development
• Infisical official docs — "Self-hosting Infisical" (Docker/Compose/Postgres+Redis, Kubernetes Helm, Linux package, AWS, GCP; compliance: SOC 2, HIPAA, FIPS 140-3; upgrade/monitoring/hardening guides), crawled 2026-10-31 — https://infisical.com/docs/self-hosting/overview
• Infisical official docs — "Inject secrets into GitHub Actions workflows" (Infisical Secrets Action; OIDC recommended — issuer https://token.actions.githubusercontent.com; Universal Auth fallback with client ID/secret in GitHub Secrets; short-lived tokens), via official docs search 2026-10-31 — https://infisical.com/docs/integrations/cicd/githubactions
• Infisical official docs — "OIDC auth with GitHub" (JWT verification flow; identity creation under Access Control > Machine Identities; claims format repo:<owner>/<repo>:<environment>), crawled 2026-10-31 — https://infisical.com/docs/documentation/platform/identities/oidc-auth/github
• Infisical official — platform positioning (open-source MIT core; self-host or Cloud US/EU; authenticates machines, engineers, agents — not end users; secret syncs outbound to K8s/Vercel/GitHub/Actions/AWS), 2026-10-31 — https://infisical.com/ai
• GitHub API — Infisical/infisical latest release v0.167.4 (published 2026-10-26), queried 2026-10-31
• DEV Community (community quick-start) — CLI usage reference (infisical init, infisical run, infisical export --format, service-token pattern, Docker integration arc), 2026 — https://dev.to/0012303/infisical-has-a-free-api-open-source-secret-management-that-replaces-env-files-23kn

Frequently asked questions

Is Infisical really open source?

Yes — the core platform is open source under the MIT license and can be self-hosted on your own infrastructure. Infisical Cloud is the managed alternative with US and EU regions. The current platform release at the time of writing is v0.167.4 (2026-10-26).

Do I have to change my application code to use Infisical?

No. The CLI injects secrets as environment variables, so your app keeps reading process.env or os.environ exactly as before. That is the whole point: secrets management changes, application code does not.

What is the difference between infisical run and infisical export?

infisical run (current docs: infisical sm run) injects secrets in-process and writes nothing to disk — that is the default you should use. infisical export writes secrets to a file like .env, which is only for tools that cannot read the environment. Treat export as the escape hatch, not the workflow.

Can I self-host Infisical instead of using the Cloud?

Yes. Official options include a single Docker container, a Docker Compose template with PostgreSQL and Redis, a Kubernetes Helm chart, a Linux package, and AWS/GCP reference architectures. Teams usually self-host for compliance (SOC 2, HIPAA, FIPS 140-3) or to keep all data under their own governance.

How should GitHub Actions authenticate to Infisical?

Use the Infisical Secrets Action with OIDC — GitHub issues a short-lived token for the workflow, Infisical verifies it, and no credential is stored in GitHub at all. Universal Auth (client ID + client secret in GitHub Secrets) is the fallback when OIDC is not available.