> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-05-13
title: Context Switching Commands (Advanced)
category: CLI
description: 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.


**Commands**: `agnt5 context` (show current), `agnt5 context use <name>`, `agnt5 context list`
**Context store**: `~/.agnt5/context.yaml`
**Default context**: `production` (API URL `https://api.agnt5.com`)
**Hidden from `--help`**: yes, but invokable directly


<Callout type="info">
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.
</Callout>

### `agnt5 context`

<CommandLayout command="context">
  <div slot="documentation">
    Prints the currently active context (defaults to `production` when none is stored) along with the API base URL pulled from `~/.agnt5/context.yaml`.

    ### Syntax
    ```bash
    agnt5 context
    ```
  </div>

  <div slot="examples">
    <ExampleBlock title="Command" variant="command">
      ```bash
      # Show current context
      agnt5 context
      ```
    </ExampleBlock>

    <ExampleBlock title="Response" variant="response">
      ```
      Current context: production
      API URL: https://api.agnt5.com
      ```
    </ExampleBlock>
  </div>
</CommandLayout>

### `agnt5 context list`

<CommandLayout command="context list">
  <div slot="documentation">
    Lists the built-in contexts (`local`, `staging`, `production`) and marks the active one with `*`.

    ### Syntax
    ```bash
    agnt5 context list
    ```
  </div>

  <div slot="examples">
    <ExampleBlock title="Command" variant="command">
      ```bash
      # List all available contexts
      agnt5 context list
      ```
    </ExampleBlock>

    <ExampleBlock title="Response" variant="response">
      ```
      Available contexts:

        local       http://localhost:34181
        staging     https://api.agnt5.xyz
      * production  https://api.agnt5.com
      ```
    </ExampleBlock>
  </div>
</CommandLayout>

### `agnt5 context set`

<CommandLayout command="context set">
  <div slot="documentation">
    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
    ```bash
    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) |
  </div>

  <div slot="examples">
    <Tabs defaultValue="local">
      <TabsList>
        <TabsTrigger value="local">Local development</TabsTrigger>
        <TabsTrigger value="staging">Staging</TabsTrigger>
        <TabsTrigger value="production">Production</TabsTrigger>
      </TabsList>

      <TabsContent value="local">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Switch to local development
          agnt5 context set local
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Context switched to: local
          ✓ Configuration copied from config.local.yaml

          Active endpoints:
            API URL: http://localhost:34181
            Gateway: http://localhost:34183
            gRPC Gateway: localhost:34184
            Auth URL: https://86934364.propelauthtest.com

          You are now targeting the local development stack.
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="staging">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Switch to staging environment
          agnt5 context set staging
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Context switched to: staging
          ✓ Configuration copied from config.staging.yaml

          Active endpoints:
            API URL: https://api.agnt5.xyz
            Gateway: https://gw.agnt5.xyz
            Auth URL: https://auth.agnt5.xyz/propelauth

          You are now targeting the staging environment.
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="production">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Switch back to production
          agnt5 context set production
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Context switched to: production
          ✓ Configuration copied from config.production.yaml

          Active endpoints:
            API URL: https://api.agnt5.com
            Gateway: https://gw.agnt5.com
            Auth URL: https://auth.agnt5.com/propelauth

          You are now targeting the production environment.
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

## 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

<Callout type="tip">
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.
</Callout>

### 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

```bash
# 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:

```bash
agnt5 context set local
agnt5 auth login
```

### Staging Testing
Use `staging` context for pre-production testing:

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

### Production Operations
Default `production` context for live deployments:

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

<Callout type="warning">
**Important:** Always verify your context before performing sensitive operations like production deployments. Use `agnt5 context` to confirm you're targeting the correct environment.
</Callout>