Cosmos (Alpha)

Cosmos is a CLI tool for managing infrastructure modules and resources, with a focus on SSH host management and extensibility.

Features

• Modular command system
• Manage SSH hosts in ~/.ssh/config
• Module for shell commands
• Module for docker containers management
• Module for stacks (docker-compose) management

Installation

Global Installation (Recommended)

Install packages globally using npm:

npm install -g @sidekick-coder/cosmos

Register the cosmos alias in your shell:

# ~/.bashrc or ~/.zshrc
alias cosmos="node $(npm root -g)/@sidekick-coder/cosmos/index.js"

Source your shell configuration:

source ~/.bashrc  # or source ~/.zshrc

Now you can run cosmos commands directly:

cosmos host list

NPX

With NPX there's no need to installation, you can just run the commands directly:

npx @sidekick-coder/cosmos [command]

Example:

npx @sidekick-coder/cosmos host list

Global Host Module (Summary)

This module lets you manage SSH host entries in your ~/.ssh/config file.

• create: Add a new host. Prompts for missing required fields.
• list: Show all hosts in a table.
• show <host>: Show details for a specific host.
• remove <name>: Remove a host entry (prompts if not provided).
• update <name>: Update a host entry. Only provided fields are updated; prompts for missing alias.

For full documentation, see docs/modules/host.md.

Global Container Module (Summary)

This lets you manage Docker containers across your registered hosts, it is useful to have an overview of all containers running on all your hosts, and to manage them easily.

• register <host>: Register a host as Docker-enabled.
• unregister <host>: Unregister a host from Docker management.
• list: List all containers across registered hosts.
• run --hostname <host> [options]: Run a new container on a host. Prompts for missing required flags.
• remove --hostname <host> <container1> [<container2> ...]: Remove one or more containers from a host.
• restart [--hosts <host1,host2,...>] [--names <container1,container2,...>]: Restart containers on one or more hosts. Prompts for confirmation if no filters are provided.

For full documentation, see docs/modules/container.md.

Host Modules

Host Modules are modules that can execute one or more actions on a VPS (Virtual Private Server) via SSH. They allow you to interact with remote hosts by running commands or performing operations directly on the server using its IP address, alias, or hostname.

To run a host module, use the following syntax:

cosmos [ip|alias|hostname] <module> [command] [args...]

• [ip|alias|hostname]: The target host's IP address, alias, or hostname.
• <module>: The host module you want to use (e.g., sh).
• [command] [args...]: The command and its arguments for the module.

Examples using the sh module

List files in a directory:

cosmos 192.168.1.10 sh ls -la /home/user

Check free memory on the host:

cosmos 192.168.1.10 sh free -h

Available Host Modules

• sh: Execute shell commands on a specified host.
• docker: Docker CLI commands.
• stacks: Manage docker compose files.

SSH Host Resolution

Cosmos uses your ~/.ssh/config file to resolve hosts and ssh keys. This means you can use any alias or host defined in your SSH config instead of typing the full IP address each time.

For example, if your ~/.ssh/config contains:

Host myserver
    HostName 192.168.1.10
    User ubuntu

Host another-server
    HostName 192.168.1.12
    User ubuntu
    IdentityFile ~/.ssh/another_key

You can run a command using the alias:

cosmos myserver sh ls -la /home/ubuntu

This will connect to 192.168.1.10 as user ubuntu using the settings from your SSH config.