Truenv CLI

The Truenv CLI syncs local .env files with the Truenv web app. The primary interface is an interactive menu: run truenv, pick a command, and answer the prompts one by one.

Direct commands still work for scripts and advanced usage.

Install

From npm:

npm install -g truenv

From this repository:

yarn install
yarn workspace truenv build
node packages/cli/dist/index.js --help

Interactive Menu

Start the interactive menu:

truenv

When you are logged out, the menu only shows login and exit.

After login, commands are visually grouped under dim section headers:

Env
  push
  pull
  history

Projects
  create-project
  init
  getdata
  list-projects
  current-project
  delete-project

Account
  whoami
  logout

Session
  exit

The command names render in the normal terminal foreground, while section headers are dimmed. Each command has a short description shown below the menu.

The menu filters commands by availability:

• push, pull, and history show only when the current folder is linked to an active project.
• init shows only when the current folder is not already linked.
• current-project shows only when .truenv.json exists.
• getdata shows when at least one project exists.
• delete-project shows when at least one active project exists.
• create-project, list-projects, whoami, logout, and exit are available when logged in.

The menu displays short descriptions for each command and waits for Enter after each command finishes before returning to the menu.

You can jump to a command by typing its first letter in the menu. For example, e highlights exit. If multiple commands share a first letter, repeated typing continues using Inquirer's built-in search behavior.

Login

Default production login:

truenv login

Local development login:

truenv login --app-url http://localhost:3000

Or set the default login target for your local shell:

TRUENV_APP_URL=http://localhost:3000 truenv login

The CLI requests a GitHub device code, copies the code to your clipboard when possible, waits for Enter, opens the GitHub verification URL, then saves the returned CLI token locally.

After login, API commands use the saved app URL and token from the local auth config. The npm-published CLI defaults to https://truenv.vercel.app unless you pass --app-url or set TRUENV_APP_URL during login.

Logout:

truenv logout

Show the signed-in CLI user:

truenv whoami

Auth config is stored in:

$XDG_CONFIG_HOME/truenv/config.json

If XDG_CONFIG_HOME is not set, it uses:

~/.config/truenv/config.json

Projects

Create a project from the current folder and link it:

truenv create-project my-app --slug my-app

Create without linking:

truenv create-project my-app --slug my-app --no-link

Link an existing project:

truenv init my-app --env local

If you do not pass a project name, Truenv opens an interactive project picker:

truenv init

This writes .truenv.json in the current directory:

{
  "projectId": "project-id",
  "environment": "local"
}

Commit .truenv.json only if you are comfortable sharing the project id and default environment name with collaborators. It does not contain env secrets or auth tokens.

Show the project linked to the current folder:

truenv current-project

Pick a project and print its id plus latest env data:

truenv getdata

Resolve directly by project id, name, or slug:

truenv getdata my-app

List projects and latest environment versions:

truenv list

In the interactive menu this appears as list-projects.

Request project deletion from the CLI:

truenv delete-project

CLI deletion is a soft delete. The project is marked pending deletion and must be confirmed from the web dashboard before it is permanently removed.

Push

Push .env to the linked project and default environment:

truenv push

Push a specific file:

truenv push --file .env.production

Push to a specific environment with a note:

truenv push --env preview --file .env.preview --note "rotated database credentials"

The CLI prints project, environment, file, parsed key count, note, created version number, and checksum.

Pull

Pull the latest env version into .env:

truenv pull

Pull a specific environment and file:

truenv pull --env preview --file .env.preview

If the target file already exists, Truenv creates a dated backup before writing the new file:

.env.2026-06-14

History

Show history for the linked environment:

truenv history

Show history for another environment:

truenv history --env production

Commands

truenv
truenv login [--app-url https://truenv.vercel.app]
truenv logout
truenv whoami
truenv create-project <project-name> [--slug project-slug] [--env local] [--no-link]
truenv delete-project [project-id]
truenv getdata [project-id-or-name]
truenv init [project-name] [--env local]
truenv push [--env local] [--file .env] [--note "rotated keys"]
truenv pull [--env local] [--file .env]
truenv list
truenv current-project
truenv history [--env local]

Security Notes

• The CLI sends env content to the Truenv API over HTTPS, except localhost is allowed for local development.
• CLI auth tokens are stored outside the project folder in the user config directory.
• .truenv.json links a folder to a project and environment, but it does not store secrets.
• Pull creates a backup before overwriting an existing env file.
• Do not commit .env files or CLI auth config.

Development

Build:

yarn workspace truenv build

Typecheck:

yarn workspace truenv typecheck

Test:

yarn workspace truenv test

Run locally after building:

node packages/cli/dist/index.js