Remotes Commands
Manage saved remote Gordon instances for easier CLI usage.
gordon remotes
Subcommands
| Subcommand | Description |
|---|---|
list |
List saved remotes |
add |
Add a new remote |
remove |
Remove a saved remote |
use |
Set active remote |
set-token |
Set or update token for a remote |
gordon remotes list
List all saved remotes.
gordon remotes list
Output
Saved Remotes
Name URL Token Status
-------------------------------------------------------------------------------
prod https://gordon.mydomain.com $PROD_TOKEN active
staging https://staging.mydomain.com set
dev https://dev.mydomain.com none
gordon remotes add
Add a new remote.
gordon remotes add <name> <url> [options]
Arguments
| Argument | Description |
|---|---|
<name> |
Name for the remote (e.g., prod, staging) |
<url> |
Gordon URL (the gordon_domain from remote config) |
Options
| Option | Description |
|---|---|
--token |
Store token directly in config |
--token-env |
Store environment variable name (token resolved at runtime) |
Examples
# Basic (no token)
gordon remotes add prod https://gordon.mydomain.com
# With direct token
gordon remotes add prod https://gordon.mydomain.com --token eyJ...
# With environment variable reference (recommended)
gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
Token Security
Option 1: Environment Variable Reference (Recommended)
gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
The remotes.toml stores only the variable name:
[remotes.prod]
url = "https://gordon.mydomain.com"
token_env = "PROD_TOKEN"
At runtime, Gordon reads $PROD_TOKEN from the environment.
Option 2: Direct Token Storage
gordon remotes add prod https://gordon.mydomain.com --token eyJ...
The token is stored directly in ~/.config/gordon/remotes.toml. Ensure restricted permissions:
chmod 600 ~/.config/gordon/remotes.toml
gordon remotes remove
Remove a saved remote.
gordon remotes remove <name>
gordon remotes remove <name> --force # Skip confirmation
Arguments
| Argument | Description |
|---|---|
<name> |
Name of the remote to remove |
Options
| Option | Description |
|---|---|
--force |
Skip confirmation prompt |
Example
gordon remotes remove staging
gordon remotes use
Set the active remote.
gordon remotes use <name>
Arguments
| Argument | Description |
|---|---|
<name> |
Name of the remote to set as active |
Description
When a remote is active, it's used automatically for all remote-capable commands without needing to specify --remote and --token:
gordon remotes use prod
gordon routes list # Uses prod remote automatically
gordon secrets list app.com # Uses prod remote automatically
Example
gordon remotes use prod
gordon remotes set-token
Set or update the authentication token for a saved remote.
gordon remotes set-token <name> <token>
Arguments
| Argument | Description |
|---|---|
<name> |
Name of the remote |
<token> |
The JWT token to set |
Description
This command is useful when:
- The server uses token-based authentication (not password auth)
- You have a pre-generated token from
gordon auth token generate - You want to update an expired token
For servers with password authentication, use gordon auth login instead.
Examples
# Set token for prod remote
gordon remotes set-token prod eyJhbGciOiJIUzI1NiIs...
# Set token from file
gordon remotes set-token staging $(cat token.txt)
# Set token from environment variable
gordon remotes set-token prod "$GORDON_TOKEN"
Output
✓ Token updated for remote 'prod'
Configuration File
Remotes are stored in ~/.config/gordon/remotes.toml:
active = "prod"
[remotes.prod]
url = "https://gordon.mydomain.com"
token_env = "PROD_TOKEN"
[remotes.staging]
url = "https://staging.mydomain.com"
token = "eyJ..."
Resolution Precedence
When multiple sources specify remote or token, the CLI uses this priority:
Remote URL:
--remoteflagGORDON_REMOTEenvironment variable- Active remote from
remotes.toml
Token:
--tokenflagGORDON_TOKENenvironment variable- Token from active remote in
remotes.toml
This allows overriding specific values while keeping defaults:
# Active remote is prod, but use different token
gordon routes list --token $TEMPORARY_TOKEN
Workflow Examples
Multi-Environment Setup
# Add all environments
gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
# Work with prod
gordon remotes use prod
gordon routes list
gordon secrets list myapp.example.com
# Switch to staging
gordon remotes use staging
gordon routes list
CI/CD Pipeline
# GitHub Actions example
env:
GORDON_REMOTE: ${{ secrets.GORDON_URL }}
GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
steps:
- name: Deploy to Gordon
run: |
gordon routes deploy myapp.example.com
Compare Environments
# Compare routes across environments
gordon routes list --remote https://gordon.example.com --token $PROD_TOKEN
gordon routes list --remote https://gordon.staging.example.com --token $STAGING_TOKEN
# Or switch between active remotes
gordon remotes use prod && gordon routes list
gordon remotes use staging && gordon routes list