Context Switching Commands (Advanced)

Switch between local development endpoints and hosted environments

Advanced users can switch between local development endpoints and hosted environments with the agnt5 context command group. Contexts influence which Control Plane and Gateway URLs the CLI uses, and they can also seed environment-specific configuration files.

Although the commands are marked hidden in --help, you can still run them directly. These are advanced commands primarily used for development and testing against different AGNT5 environments.

`agnt5 context`

Prints the currently active context (defaults to production when none is stored) along with the API base URL pulled from ~/.agnt5/context.yaml.

Syntax

agnt5 context

Command

# Show current context
agnt5 context

Response

Current context: production
API URL: https://api.agnt5.com

`agnt5 context list`

Lists the built-in contexts (local, staging, production) and marks the active one with *.

Syntax

agnt5 context list

Command

# List all available contexts
agnt5 context list

Response

Available contexts:

  local       http://localhost:34181
  staging     https://api.agnt5.xyz
* production  https://api.agnt5.com

`agnt5 context set`

Writes the chosen context to ~/.agnt5/context.yaml, updates related settings, and copies ~/.agnt5/config.<context>.yaml into config.yaml when present. The command also prints the final API and gateway URLs so you can confirm the change.

Syntax

agnt5 context set <context>

Available Contexts

Context	API URL	Gateway URL	Notes
`local`	`http://localhost:34181`	`http://localhost:34183`	Dev stack with local OAuth
`staging`	`https://api.agnt5.xyz`	`https://gw.agnt5.xyz`	Pre-production testing
`production`	`https://api.agnt5.com`	`https://gw.agnt5.com`	Live environment (default)

Context Configuration

Every context also updates agnt5_env to a descriptive value (agnt5-local, agnt5-staging, agnt5-production). Commands like agnt5 auth login and agnt5 deploy pick up these values the next time they run, ensuring you are talking to the correct control plane.

Environment-Specific Configuration

Keep environment-specific credentials in ~/.agnt5/config.local.yaml, config.staging.yaml, etc. Switching contexts copies the relevant file over config.yaml, so your API keys stay in sync with the environment you just selected.

Configuration Files by Context

File	Purpose
`~/.agnt5/context.yaml`	Stores the currently active context
`~/.agnt5/config.yaml`	Main configuration file, updated when contexts switch
`~/.agnt5/config.local.yaml`	Local environment-specific settings
`~/.agnt5/config.staging.yaml`	Staging environment-specific settings
`~/.agnt5/config.production.yaml`	Production environment-specific settings

Context Workflow

# 1. Check current context
agnt5 context

# 2. List available contexts
agnt5 context list

# 3. Switch to local development
agnt5 context set local

# 4. Authenticate against local environment
agnt5 auth login

# 5. Work with local stack
agnt5 project list

# 6. Switch back to production
agnt5 context set production

Use Cases

Local Development

Switch to local context when working with the development stack:

agnt5 context set local
agnt5 auth login

Staging Testing

Use staging context for pre-production testing:

agnt5 context set staging
agnt5 auth login
agnt5 deploy --staging

Production Operations

Default production context for live deployments:

agnt5 context set production
agnt5 auth login
agnt5 deploy --prod

Important: Always verify your context before performing sensitive operations like production deployments. Use agnt5 context to confirm you’re targeting the correct environment.