# Your First Project

Create a KeyEnv project and sync your first secrets in under 5 minutes.

Source: https://keyenv.dev/docs/getting-started/first-project/

This tutorial walks you through the complete KeyEnv workflow: authenticating, creating a project, managing secrets, and running your application with secrets injected.

**Prerequisites:**
- [KeyEnv CLI installed](/docs/getting-started/installation)
- A KeyEnv account ([sign up here](https://app.keyenv.dev/signup))

---

## Step 1: Login

Authenticate with your KeyEnv account:

```bash
keyenv login
```

This opens your browser for authentication. Once complete, you'll see:

```
✓ Logged in as you@example.com
✓ Access token saved to keychain
```

Verify your session anytime with:

```bash
keyenv whoami
```

---

## Step 2: Initialize a Project

Navigate to your project directory:

```bash
cd ~/my-project
keyenv init
```

You'll be prompted to either select an existing project or create a new one:

```
? Select a project:
❯ Create new project
  my-existing-project
  another-project
```

If creating new, enter a project name:

```
? Project name: my-awesome-app
? Default environment: development

✓ Project 'my-awesome-app' created
✓ Configuration saved to .keyenv.toml
```

This creates a `.keyenv.toml` configuration file:

```toml
project_id = "abc123-def456-..."
default_environment = "development"
```

> **Note**
>
> The `.keyenv.toml` file is safe to commit. It only contains the project ID, not secrets.

---

## Step 3: Add Your First Secrets

Add secrets using the CLI:

```bash
# Set a simple secret
keyenv set DATABASE_URL "postgres://localhost:5432/mydb"

# Set multiple secrets
keyenv set API_KEY "your-api-key"
keyenv set JWT_SECRET "your-jwt-secret"
```

For sensitive values, pipe from stdin to avoid shell history:

```bash
echo "sk_live_abc123..." | keyenv set STRIPE_SECRET_KEY -
```

List your secrets to verify:

```bash
keyenv list
```

Output:

```
Environment: development

DATABASE_URL      postgres://localhost:5432/mydb
API_KEY           your-*****-key
JWT_SECRET        ********
STRIPE_SECRET_KEY sk_live_*****
```

---

## Step 4: Pull Secrets to .env

Sync secrets to a local `.env` file:

```bash
keyenv pull
```

Output:

```
✓ Pulled 4 secrets to .env
```

Your `.env` file now contains:

```
DATABASE_URL=postgres://localhost:5432/mydb
API_KEY=your-api-key
JWT_SECRET=your-jwt-secret
STRIPE_SECRET_KEY=sk_live_abc123...
```

> **Warning**
>
> Add `.env` to your `.gitignore` to prevent accidentally committing secrets.

---

## Step 5: Run with Secrets Injected

The recommended way to use secrets is with `keyenv run`. This injects secrets as environment variables without writing them to disk:

```bash
keyenv run -- npm start
```

Or with any command:

```bash
# Node.js
keyenv run -- node server.js

# Python
keyenv run -- python app.py

# Docker
keyenv run -- docker-compose up
```

The `--` separates KeyEnv options from your command.

---

## Step 6: Work with Different Environments

KeyEnv supports multiple environments (development, staging, production). Specify the environment using the `-e/--env` flag:

```bash
# Pull staging secrets
keyenv pull --env staging

# Run with production secrets
keyenv run --env production -- npm start

# Set a default environment in .keyenv.toml
# Edit the file and change: default_environment = "staging"
```

> **Note**
>
> The `-e/--env` flag works with most commands (`pull`, `push`, `run`, `set`, `get`, `list`). To change your default environment, edit the `default_environment` value in your `.keyenv.toml` file.

---

## What's Next?

You've learned the basics! Here's where to go next:

- **[Core Concepts](/docs/getting-started/concepts)** - Understand projects, environments, and teams
- **[CLI Reference](/docs/cli)** - Complete command documentation
- **[CI/CD Integration](/docs/guides/ci-cd)** - Set up secrets in your pipeline
- **[Docker Guide](/docs/guides/docker)** - Use KeyEnv with containers

---

## Quick Reference

| Command | Description |
|---------|-------------|
| `keyenv login` | Authenticate with KeyEnv |
| `keyenv init` | Initialize a project |
| `keyenv set KEY value` | Set a secret |
| `keyenv get KEY` | Get a secret value |
| `keyenv list` | List all secrets |
| `keyenv pull` | Sync secrets to .env |
| `keyenv run -- cmd` | Run command with secrets |
| `keyenv push` | Push local .env to server |