Skip to main content

​
Overview

Every command that needs a private key follows the same lookup order. This avoids requiring --private-key on every command while still allowing explicit overrides.

​
Private Key Lookup Order

  1. --private-key <path> flag (if provided) — Use this file directly.
  2. COWBOY_PRIVATE_KEY environment variable — If set, treat the value as a hex-encoded 32-byte private key.
  3. .cowboy/config.json — Read key_file from the active environment, resolved relative to .cowboy/.
  4. .cowboy/key — Fallback for backward compatibility (walk up from the current directory to find the nearest .cowboy/key file, same pattern as .git/ discovery).
If none of these produce a key, the command prints an error:

​
Key File Formats

The CLI supports two key file formats and auto-detects which is in use: PEM format (current default):
Hex format (backward compatible):
The 0x prefix is accepted but not required for hex format. Trailing newlines are trimmed. Use cowboy wallet upgrade to convert hex keys to PEM format.

​
Directory Walking

The CLI searches for .cowboy/ starting from the current working directory and walking up to the filesystem root:
This allows nested directories within a project to find the project-level key.

​
RPC URL Discovery

The same pattern applies to the RPC URL:
  1. --rpc-url <url> flag (if provided).
  2. COWBOY_RPC_URL environment variable.
  3. .cowboy/config.json file (read rpc_url from the active environment).
  4. Default: http://localhost:4000.
The config.json format (multi-environment):
The legacy flat format is also supported:

​
Commands Using Auto-Discovery

Every command that needs a private key or RPC URL uses auto-discovery. This is critical for the zero-config promise — after cowboy init dev or cowboy init local, commands use the configured key and network without extra flags.