Creating Your First Project

dotEnv Cloud organizes secrets in a clear hierarchy. Understanding it is the key to using the platform effectively. This guide explains each level and shows you how to create your first project, target, and environment.

The hierarchy

Secrets live inside a four-level structure. Each level can hold its own secrets, and child levels inherit from their parents:

hierarchy

organization # your team or company

└─ project # an application or service

└─ target # a deployment tier (production, staging…)

└─ environment # a specific runtime (api, web, worker…)

Organization: the top-level account that owns everything and to which API keys and members are scoped.
Project: a single application or service. Each project has its own encryption key.
Target: a deployment tier such as production or staging.
Environment: a concrete runtime within a target, like api or web.

Create a project

With the CLI authenticated, create a project inside your current organization:

terminal

dotenv project create my-app

Add a target

Targets are created under a project. A common starting point is a production and a staging target:

terminal

dotenv target create my-app production

dotenv target create my-app staging

Add an environment

Environments are created under a target. Here we add an api environment to the production target:

terminal

dotenv environment create my-app production api

The environment command also accepts the shorter env alias.

Browse what you built

Use dotenv list to walk the hierarchy. Pass the resource type you want to see, optionally narrowed by a path:

terminal

# Projects in the current organization

dotenv list projects

# Targets in a project

dotenv list targets my-app

# Environments in a project/target

dotenv list environments my-app/production

# Everything as a flat table

dotenv list all

For an interactive walk-through of your hierarchy, try dotenv explore, which lets you navigate projects, targets, and environments from a single prompt.

Reference levels by path

Throughout the CLI you address a level using a project/target/environment path. Every segment after the project is optional, so all of these are valid:

terminal

my-app # project level

my-app/production # target level

my-app/production/api # environment level

Now that your structure exists, move on to Managing Environment Variables to push and pull secrets.