devo ssm¶

AWS Systems Manager Session Manager commands for database and instance connections.

Synopsis¶

devo ssm <command> [OPTIONS]
devo ssm database <subcommand> [OPTIONS]
devo ssm instance <subcommand> [OPTIONS]
devo ssm hosts <subcommand> [OPTIONS]

Description¶

Manages SSM port forwarding connections to private databases and services through bastion instances. Supports hostname forwarding using /etc/hosts and loopback IPs for seamless application integration.

Commands¶

Shortcuts¶

connect¶

Shortcut for devo ssm database connect.

devo ssm connect [NAME] [OPTIONS]

shell¶

Shortcut for devo ssm instance shell.

devo ssm shell NAME

database¶

Manage database connections.

devo ssm database <subcommand> [OPTIONS]

database connect¶

Connect to a configured database (uses hostname forwarding by default).

devo ssm database connect [NAME] [OPTIONS]

Option	Required	Default	Description
`NAME`	No	-	Database name (shows menu if omitted)
`--no-hosts`	No	`false`	Disable hostname forwarding, use localhost

Example:

# Connect with menu selection
devo ssm database connect
# → Opens interactive menu; starts SSM tunnel and keeps it running in the foreground

# Connect to specific database
devo ssm database connect mydb
# → Starts SSM port-forward tunnel; connect your DB client to mydb:<port>

# Connect without hostname forwarding
devo ssm database connect mydb --no-hosts
# → Tunnel available at localhost:<port> instead of the configured hostname

# Using shortcut
devo ssm connect mydb
# → Same as devo ssm database connect mydb

database list¶

List all configured databases.

devo ssm database list

Example:

devo ssm database list

database add¶

Add a database configuration.

devo ssm database add --name NAME --bastion BASTION --host HOST --port PORT [OPTIONS]

Option	Required	Default	Description
`--name`	Yes	-	Configuration name
`--bastion`	Yes	-	Bastion instance ID
`--host`	Yes	-	Database hostname
`--port`	Yes	-	Remote port
`--local-port`	No	Same as `--port`	Local port for forwarding
`--region`	No	`us-east-1`	AWS region
`--profile`	No	-	AWS profile

Example:

devo ssm database add --name mydb --bastion i-xxx --host db.rds.amazonaws.com --port 5432

database remove¶

Remove a database configuration.

devo ssm database remove NAME

Argument	Required	Description
`NAME`	Yes	Database name to remove

Example:

devo ssm database remove mydb

instance¶

Manage EC2 instance connections.

devo ssm instance <subcommand> [OPTIONS]

instance shell¶

Connect to a configured instance via interactive shell.

devo ssm instance shell NAME

Argument	Required	Description
`NAME`	Yes	Instance name

Example:

# Connect to specific instance
devo ssm instance shell bastion-dev
# → Opens an interactive SSM shell session on the EC2 instance

# Using shortcut
devo ssm shell bastion-dev
# → Same as devo ssm instance shell bastion-dev

instance list¶

List all configured instances.

devo ssm instance list

Example:

devo ssm instance list

instance add¶

Add an EC2 instance configuration.

devo ssm instance add --name NAME --instance-id INSTANCE_ID [OPTIONS]

Option	Required	Default	Description
`--name`	Yes	-	Instance configuration name
`--instance-id`	Yes	-	EC2 instance ID
`--region`	No	`us-east-1`	AWS region
`--profile`	No	-	AWS profile

Example:

devo ssm instance add --name bastion-dev --instance-id i-xxx --region us-east-1

instance remove¶

Remove an instance configuration.

devo ssm instance remove NAME

Argument	Required	Description
`NAME`	Yes	Instance name to remove

Example:

devo ssm instance remove bastion-dev

hosts¶

Manage /etc/hosts entries for hostname forwarding.

devo ssm hosts <subcommand> [OPTIONS]

hosts setup¶

Setup /etc/hosts entries for all configured databases.

devo ssm hosts setup

Automatically assigns unique loopback IPs, updates /etc/hosts, and saves configuration.

Example:

devo ssm hosts setup
# → Writes loopback IP entries (e.g. 127.0.0.2 mydb.cluster-xyz...) to /etc/hosts for all configured databases

hosts list¶

List all /etc/hosts entries managed by Devo CLI.

devo ssm hosts list

Example:

devo ssm hosts list

hosts add¶

Add a single database hostname to /etc/hosts.

devo ssm hosts add NAME

Argument	Required	Description
`NAME`	Yes	Database name

Example:

devo ssm hosts add mydb

hosts remove¶

Remove a database hostname from /etc/hosts.

devo ssm hosts remove NAME

Argument	Required	Description
`NAME`	Yes	Database name

Example:

devo ssm hosts remove mydb

hosts sync¶

Make /etc/hosts match the databases in one go: add or fix the entries of the databases with hostname forwarding on, and remove the stale ones (hostnames in Devo's block that no database forwards anymore: deleted, with another host now, or paused). Entries outside Devo's block are never touched.

It also repairs databases set up on the same loopback IP and port: only one of them could be reached through its hostname (the other one's tunnel might answer instead). One of each pair gets its own 127.0.0.X; clients keep using the same hostname and port.

devo ssm hosts sync

hosts clear¶

Remove all Devo CLI managed entries from /etc/hosts.

devo ssm hosts clear

Prompts for confirmation before removing all entries.

Example:

devo ssm hosts clear

Paused hostname forwarding¶

Devo Desktop can pause hostname forwarding for all databases or for one, so their hostnames resolve through normal DNS (e.g. to reach them over a VPN). ssm.hostname_forwarding in ~/.devo/config.json is the setting for all databases; ssm.databases.<name>.hostname_forwarding, when present, is an exception for that one (e.g. one forwarded while the rest is paused). The CLI follows it:

devo ssm connect connects paused databases on 127.0.0.1, as with --no-hosts, and doesn't offer to set up their hosts entries
devo ssm hosts setup skips paused databases

forward¶

Manual port forwarding without saving configuration.

devo ssm forward [OPTIONS]

Option	Required	Default	Description
`--bastion`	Yes	-	Bastion instance ID
`--host`	Yes	-	Database/service hostname
`--port`	No	`5432`	Remote port
`--local-port`	No	Same as `--port`	Local port for forwarding
`--region`	No	`us-east-1`	AWS region
`--profile`	No	-	AWS profile

Example:

devo ssm forward --bastion i-xxx --host db.rds.amazonaws.com --port 5432

Platform Support¶

Feature	Linux	macOS	Windows
Basic SSM forwarding	✅	✅	✅
Hostname forwarding	✅	✅	✅
/etc/hosts management	✅	✅	✅
Loopback IPs (127.0.0.x)	✅	✅	✅

Requirements¶

All Platforms¶

AWS Session Manager Plugin (separate from AWS CLI)
Verify: session-manager-plugin

Platform-Specific¶

Linux / macOSWindows

socat for hostname forwarding
sudo access for /etc/hosts modification

netsh portproxy (built-in, no installation needed)
Administrator privileges for hostname forwarding setup only

Configuration File Format¶

SSM configuration is stored under the ssm key in ~/.devo/config.json:

{
  "ssm": {
    "databases": {
      "mydb": {
        "bastion": "i-0123456789abcdef0",
        "host": "mydb.cluster-xyz.us-east-1.rds.amazonaws.com",
        "port": 5432,
        "local_port": 5432,
        "local_address": "127.0.0.2",
        "region": "us-east-1",
        "profile": "dev"
      }
    },
    "instances": {
      "bastion-dev": {
        "instance_id": "i-0123456789abcdef0",
        "region": "us-east-1",
        "profile": "dev"
      }
    }
  }
}

Environment Variables¶

Variable	Description	Default
`AWS_PROFILE`	AWS profile for credentials	Default profile
`AWS_REGION`	AWS region	`us-east-1`

Exit Codes¶

Code	Description
0	Success
1	Error (configuration not found, connection failed, etc.)

Common Workflows¶

Initial Setup¶

# 1. Add a database
devo ssm database add --name mydb --bastion i-xxx --host db.rds.amazonaws.com --port 5432

# 2. Setup hostname forwarding
devo ssm hosts setup

# 3. Connect
devo ssm connect mydb

Daily Usage¶

# Connect to database (using shortcut)
devo ssm connect mydb

# Connect to instance shell (using shortcut)
devo ssm shell bastion-dev

# List all databases
devo ssm database list

# List all instances
devo ssm instance list

# Export SSM configuration
devo config export -s ssm -o team-ssm-config.json

# Share team-ssm-config.json with team

# Import on another machine
devo config import team-ssm-config.json -s ssm

Troubleshooting¶

# List current hosts entries
devo ssm hosts list

# Clear all hosts entries
devo ssm hosts clear

# Re-setup hosts
devo ssm hosts setup

# Connect without hostname forwarding
devo ssm connect mydb --no-hosts

devo ssm¶

Synopsis¶

Description¶

Commands¶

Shortcuts¶

connect¶

shell¶

database¶

database connect¶

database list¶

database add¶

database remove¶

instance¶

instance shell¶

instance list¶

instance add¶

instance remove¶

hosts¶

hosts setup¶

hosts list¶

hosts add¶

hosts remove¶

hosts sync¶

hosts clear¶

Paused hostname forwarding¶

forward¶

Platform Support¶

Requirements¶

All Platforms¶

Platform-Specific¶

Configuration File Format¶

Environment Variables¶

Exit Codes¶

Common Workflows¶

Initial Setup¶

Daily Usage¶

Team Configuration Sharing¶

Troubleshooting¶

See Also¶