Environment Setup

📄 Last updated: Nov 14, 2025 v2.0.4

Prerequisites

Before setting up your local environment, ensure your system meets the following requirements:

Node.js >= 18.0.0 (LTS recommended)
npm >= 9.0.0 or yarn >= 1.22.0
Git >= 2.30.0
macOS 12+, Ubuntu 20.04+, or Windows 10/11 with WSL2
At least 4GB RAM available for builds

ℹ️

Tip: Use nvm (Node Version Manager) to easily switch between Node.js versions across projects.

Install the .git CLI

The git-cli is the primary tool for initializing, configuring, and managing your .git workspace.

1. Global Installation

Terminal

npm install -g @gitdev/cli
# or with yarn
yarn global add @gitdev/cli

2. Verify Installation

Terminal

git-cli --version
# Expected output: git-cli/2.0.4 (linux-x64) node/v20.11.0

Configure Environment Variables

Create a .env file in your project root. The CLI will automatically load it during initialization and runtime.

.env

GIT_DEV_TOKEN=your_api_token_here
GIT_DEV_ORG=your-organization-slug
GIT_DEV_REGION=us-east-1
GIT_DEV_LOG_LEVEL=info
GIT_DEV_PREVIEW=true

Variable Reference

Variable	Type	Description
`GIT_DEV_TOKEN`	string	Authentication token generated from your dashboard
`GIT_DEV_ORG`	string	Your organization or workspace identifier
`GIT_DEV_REGION`	string	Primary deployment region (default: auto)
`GIT_DEV_LOG_LEVEL`	enum	`debug`, `info`, `warn`, `error`
`GIT_DEV_PREVIEW`	boolean	Enable live preview URLs for commits

⚠️

Security: Never commit .env to version control. Add it to .gitignore immediately after creation.

Initialize & Verify

Run the setup command to link your environment with your .git workspace:

Terminal

git-cli init --workspace my-project
git-cli link --env .env

Upon successful configuration, you'll see:

Terminal Output

✓ Authenticated with .git
✓ Workspace 'my-project' initialized
✓ Environment variables loaded (5)
✓ Build pipeline configured
➜ Ready to commit & deploy

✅

Success! Your environment is now configured. Push changes with git push and .git will handle builds, tests, and deployments automatically.

Troubleshooting

"EACCES permission denied" during installation: Use npx or run with sudo (Linux/macOS). On Windows, ensure admin privileges or use PowerShell as Administrator.
"Invalid token": Regenerate your API token in Dashboard > Settings > API Keys and update GIT_DEV_TOKEN.
Slow builds: Check GIT_DEV_LOG_LEVEL=debug output. Ensure Node.js >= 18 and clear node_modules before rebuilding.
WSL2 issues: Run wsl --update and ensure you're using /mnt/c/ paths correctly for Windows integration.

Still stuck? Visit our Community Forum or open a GitHub Issue.

→ Project Configuration

Set up branches, CI/CD rules, and environment-specific overrides.

→ Deploy Your First Commit

Learn how git push triggers automated previews and production rolls.