Your first project

Create a project

From the directory of the codebase you want to track:

handoff init

You'll be prompted for a project slug and a first environment name. This creates a .handoff/config.json file in the current directory; commit it. It only holds the project ID and default environment, not any secrets.

You can also pass everything up front:

handoff init --project my-service --env dev

Push your .env

If you already have a .env file, push it up:

handoff push

push uses the default environment from .handoff/config.json. To target a different one:

handoff push --env staging

By default Handoff shows you a diff and asks for confirmation. Skip the prompt with --yes.

Pull on another machine

On a teammate's machine (or your laptop, or CI), from the same repo:

handoff pull

Handoff writes a fresh .env.<env> (for example, .env.dev) so pulling never clobbers your primary .env by accident. Point it somewhere else with --out:

handoff pull --env production --out .env.production

If the destination file already exists, pull refuses to overwrite. Pass --force in non-interactive contexts.

Prefer injecting at runtime?

If you prefer injecting secrets at runtime, rather than writing them to disk, you can use handoff run. This is great for CI/CD pipelines, or if secrets change frequently.

handoff run --env production -- ./start.sh

See handoff run for more information.

What's next?

• Learn the full CLI surface
• Wire up CI with handoff run and an API token
• See how to use Handoff inside GitHub Actions