# Configuration Commands

Manage environment variables, secrets, and API keys from the CLI.

These CLI commands help you manage configuration values for your deployed agents.

> [!NOTE]
> **Cloud Prefix Required**
> All configuration commands require the `cloud` prefix. For example: `agentuity cloud env list`

## Environment Variables

Manage non-sensitive configuration values.

### List Variables

```bash
agentuity cloud env list
```

### Get a Variable

```bash
agentuity cloud env get NODE_ENV
```

### Set a Variable

```bash
agentuity cloud env set NODE_ENV production
agentuity cloud env set API_URL https://api.example.com
```

### Delete a Variable

```bash
agentuity cloud env delete OLD_CONFIG
```

### Push from Local File

Upload variables from `.env` to cloud:

```bash
agentuity cloud env push
```

This filters out `AGENTUITY_` prefixed keys automatically.

### Pull to Local File

Download cloud variables to `.env`:

```bash
# Merge with local (local values take priority)
agentuity cloud env pull

# Overwrite local with cloud values
agentuity cloud env pull --force
```

### Import from File

```bash
agentuity cloud env import .env.staging
```

> [!WARNING]
> **Secrets vs Environment Variables**
> Use `cloud secret` for sensitive values like API keys and database passwords. Use `cloud env` for non-sensitive configuration like feature flags and URLs.

## Secrets

Manage sensitive values like API keys and tokens. Commands mirror `cloud env`.

### List Secrets

```bash
agentuity cloud secret list
```

### Get a Secret

```bash
agentuity cloud secret get API_KEY
```

### Set a Secret

```bash
agentuity cloud secret set API_KEY "sk_live_..."
agentuity cloud secret set DATABASE_URL "postgresql://..."
```

### Delete a Secret

```bash
agentuity cloud secret delete OLD_TOKEN
```

### Push/Pull

```bash
# Push from local file
agentuity cloud secret push

# Pull to local file
agentuity cloud secret pull
agentuity cloud secret pull --force
```

### Import from File

```bash
agentuity cloud secret import .env.secrets
```

**In agents:** Access secrets via `process.env.API_KEY`. Secrets are injected at runtime and never logged.

## Organization-Level Configuration

Set environment variables and secrets at the organization level to share them across all projects in that organization. Use the `--org` flag with any `env` or `secret` command.

### Set Org-Level Variables

```bash
# Set using your default org
agentuity cloud env set DATABASE_URL "postgresql://..." --org

# Set for a specific org
agentuity cloud env set DATABASE_URL "postgresql://..." --org org_abc123
```

### Set Org-Level Secrets

```bash
# Set shared secret for default org
agentuity cloud secret set SHARED_API_KEY "sk_..." --org

# Set for specific org
agentuity cloud secret set SHARED_API_KEY "sk_..." --org org_abc123
```

### List Org-Level Values

```bash
# List org environment variables
agentuity cloud env list --org

# List org secrets
agentuity cloud secret list --org
```

### Get/Delete Org-Level Values

```bash
# Get an org variable
agentuity cloud env get DATABASE_URL --org

# Delete an org secret
agentuity cloud secret delete OLD_KEY --org
```

> [!NOTE]
> **Inheritance**
> Organization-level values are inherited by all projects in that organization. Project-level values take precedence over organization-level values when both are set.

> [!TIP]
> **Default Organization**
> Set a default organization with `agentuity auth org select` to avoid specifying `--org` on every command. If you use multiple accounts or organizations, see [CLI Profiles](/reference/cli/profiles) for separate defaults.

## API Keys

Create and manage API keys for programmatic access to your project.

### Create an API Key

```bash
# With 1 year expiration
agentuity cloud apikey create --name "Production Key" --expires-at 1y

# With 30 day expiration
agentuity cloud apikey create --name "Short-lived Key" --expires-at 30d

# With specific date
agentuity cloud apikey create --name "Q1 Key" --expires-at 2026-03-31T23:59:59Z

# Skip confirmation prompt
agentuity cloud apikey create --name "CI/CD Key" --expires-at 90d --confirm
```

> [!WARNING]
> **Save Your Key**
> The API key value is shown only once during creation. Copy it immediately; you cannot retrieve it later.

### List API Keys

```bash
agentuity cloud apikey list
```

### Get API Key Details

```bash
agentuity cloud apikey get <key-id>
```

This shows metadata (name, expiration) but not the key value.

### Delete an API Key

```bash
agentuity cloud apikey delete <key-id>
```

> [!NOTE]
> **Using API Keys**
> API keys authenticate requests to Agentuity APIs. Store them in your `.env` as `AGENTUITY_SDK_KEY`:
>
> ```bash
> AGENTUITY_SDK_KEY=agt_...
> ```

## Next Steps

- [Storage Commands](/reference/cli/storage): Manage KV, S3, Vector, Database, and Streams
- [Deployment Commands](/reference/cli/deployment): Deploy and manage your agents
- [Development Commands](/reference/cli/development): Local development workflow