Skip to main content

​
Synopsis

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: 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: Example:

​
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: Example:

​
cowboy env list

List configured environments. Example:
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: Example:

​
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.