> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# cowboy env

> Manage local Cowboy environment metadata in .cowboy/config.json

## Synopsis

```bash theme={null}
cowboy env add <name> [--rpc-url <url>] [--key <name>] [--json]
cowboy env use [<name>] [--json]
cowboy env list [--json]
cowboy env current [--json]
```

Environment commands are local-only: they read and write `.cowboy/config.json` and never contact a node. `--rpc-url` is the global flag; `env add` records it as the new environment's endpoint. Four names have built-in defaults and need no prior `add`:

| Name | Default RPC URL |
| - | - |
| `local` | `http://localhost:4000` |
| `mesa` | `https://rpc.mesa.cowboylabs.net` |
| `dev` (an alias for Mesa) | `https://rpc.mesa.cowboylabs.net` |
| `canyon` | `https://rpc.canyon.cowboylabs.net` |

Any other name is a project-configured environment and needs `--rpc-url` when added.

## Subcommands

### `cowboy env add`

Add environment metadata without creating a wallet.

**Behavior:**

1. Discover the project's `.cowboy` directory from the current directory.
2. Resolve the RPC URL: `--rpc-url` if given, else the built-in default for the name. A name with no built-in default and no `--rpc-url` fails with `rpc_url_required`.
3. Write the environment and print `Added environment '<name>'.` with its RPC URL, key, and whether it is active. Re-adding an identical environment prints `Environment '<name>' is already configured; no changes made.`

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `<name>` | Required | Environment name |
| `--rpc-url` | Built-in default for the name | RPC endpoint URL; required when the name has no built-in default |
| `--key` | `default` | Name of the keystore key (`~/.cowboy/keys/<NAME>`) the environment signs with: 1 to 64 lowercase letters, digits, `.`, `_` or `-`, starting with a letter or digit (`invalid_key_name` otherwise) |
| `--json` | `false` | Emit one versioned JSON result object (`env.add`, with `changed` and `environment`) |

**Example:**

```bash theme={null}
$ cowboy env add staging --rpc-url https://rpc.staging.example
✓ Added environment 'staging'.
  RPC URL: https://rpc.staging.example
  Key: default
  Active: no
```

***

### `cowboy env use`

Select the active environment.

**Behavior:**

1. With a name, select that environment. Built-in names are configured on first use.
2. With no name, prompt with a menu: `Local`, `Mesa`, `Canyon` (each marked `(active)`, `(configured)`, or, for Canyon, `(private network access required)`), followed by any project-configured environments. Without an interactive terminal the prompt fails and the error suggests `cowboy env use canyon`.
3. Print `Using environment '<name>'.` with its details, or `Environment '<name>' is already active; no changes made.`

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `<name>` | Prompt (required with `--json`) | Environment name |
| `--json` | `false` | Emit one versioned JSON result object (`env.use`) |

**Example:**

```bash theme={null}
$ cowboy env use canyon
✓ Using environment 'canyon'.
  RPC URL: https://rpc.canyon.cowboylabs.net
  Key: default
  Active: yes
```

***

### `cowboy env list`

List configured environments.

**Example:**

```bash theme={null}
$ cowboy env list
Environments:
* local
    RPC URL: http://localhost:4000
    Key: default
  mesa
    RPC URL: https://rpc.mesa.cowboylabs.net
    Key: default
```

The active environment is marked with `*`. With none configured, prints `No environments configured.` Under `--json` the result has `active` and `environments`.

***

### `cowboy env current`

Show the environment, RPC URL, and signer the shared lookup resolves in this directory, and where each came from (reads no network). `deploy`, commands on a deployed target, and `faucet request` resolve some of these on their own.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--json` | `false` | Emit one versioned JSON result object (`env.current`: `environment`, `rpc_url`, `signer`, `non_interactive`) |

**Example:**

```bash theme={null}
$ cowboy env current
  Environment: mesa (from /home/you/my-app/.cowboy/config.json)
  RPC URL: https://rpc.mesa.cowboylabs.net (from environment)
  Signer: 0x7a3B...F92E (from keystore)
  Mode: interactive
```

## Edge Cases

* `env add` cannot silently repoint an existing environment's RPC URL or key; the CLI refuses with `environment_conflict`.
* An unusable `.cowboy/config.json` fails `env add`, `env use`, and `env list` with `config_invalid`. This includes an environment that names a key file with `key_file` (replace it with `"key": "<name>"` and move the key into the keystore) and the old flat `{"network", "rpc_url"}` format (rewrite it as `active`/`environments` with a key name).
* RPC URLs are sanitized in JSON output (embedded credentials are not echoed).
* Names and URLs containing control characters are escaped when printed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.