Skip to content

cli.md

Latest commit

 

History

History
164 lines (152 loc) · 6.5 KB

cli.md

File metadata and controls

164 lines (152 loc) · 6.5 KB

Bolt CLI Documentation

Overview

The Bolt CLI is a Python-based command-line interface for interacting with the Bolt server. It provides a user-friendly, context-aware interface to manage projects, sandboxes, port forwarding, resource limits, and shell access. The CLI supports all server features, displays accurate runtime information, and checks for server updates.

Features

  • Connection Management: Add and connect to Bolt servers with stored credentials.
  • Project Management: Create, delete, and open projects.
  • Sandbox Management: Create, delete, open, and list sandboxes within projects.
  • Port Forwarding: Configure host-to-sandbox and sandbox-to-host port forwarding.
  • Resource Limits: Set CPU and memory limits for projects.
  • Shell Access: Connect to sandbox shells via a secure TCP connection with token authentication.
  • Status Reporting: Display server and sandbox status with real-time system metrics.
  • Update Checks: Check for server updates and display version information.
  • Context-Aware Prompt: Reflects the current server, project, sandbox, or shell context.

Requirements

  • Python 3 and the requests package.
  • Access to a running Bolt server.

Installation

Step 1: Install Dependencies

pip3 install requests

Step 2: Install CLI

Copy the bolt_cli.py script to a convenient location:

cp bolt_cli.py ~/bolt_cli.py
chmod +x ~/bolt_cli.py

Optionally, add it to your PATH:

sudo cp ~/bolt_cli.py /usr/local/bin/bolt

Configuration

The CLI stores server connections in ~/.bolt/config.json:

{
    "servers": {
        "server1": {
            "ip": "127.0.0.1",
            "username": "admin",
            "password": "admin"
        }
    },
    "current_server": "server1"
}
  • The file is created automatically with 0600 permissions.
  • Credentials are prompted if not stored and saved securely.

Usage

Run the CLI interactively or with commands:

bolt
bolt <command> [args]

Commands

  • add : Add a new server connection.
    • Example: bolt add server1 127.0.0.1
  • connect : Connect to a server, prompting for credentials if needed.
    • Example: bolt connect server1
  • create project : Create a new project.
    • Example: create project project1
  • create sandbox [distro]: Create a sandbox in the current project.
    • Example: create sandbox sandbox1 debian:bullseye
  • delete project : Delete a project and its sandboxes.
    • Example: delete project project1
  • delete sandbox : Delete a sandbox from the current project.
    • Example: delete sandbox sandbox1
  • open project : Set the current project context.
    • Example: open project project1
  • open sandbox : Set the current sandbox context.
    • Example: open sandbox sandbox1
  • sandboxes: List sandboxes in the current project with runtime and distro.
    • Example: sandboxes
  • info: Show detailed info for the current sandbox (runtime, resources, ports).
    • Example: info
  • shell: Open a TCP shell to the current sandbox, prompting for a token.
    • Example: shell
  • forward <host_port> <container_port>: Forward a host port to a sandbox port.
    • Example: forward 10001 80
  • reverse <container_port> <host_port>: Forward a sandbox port to a host port.
    • Example: reverse 8080 10002
  • remove_forward <host_port>: Remove a host-to-sandbox port forwarding.
    • Example: remove_forward 10001
  • remove_reverse <container_port>: Remove a sandbox-to-host port forwarding.
    • Example: remove_reverse 8080
  • resources <cpu_quota_us> <memory_limit_mb>: Set resource limits for the current project.
    • Example: resources 50000 256
  • config : Update server admin credentials.
    • Example: config newadmin newpass
  • status: Show server status (sandboxes, CPU, RAM, storage).
    • Example: status
  • update: Show server update information.
    • Example: update
  • exit or quit: Exit the CLI.
    • Example: exit

Example Session

$ bolt
bolt $ add server1 127.0.0.1
Created new saved connection: server1 to 127.0.0.1!
bolt $ connect server1
Username for server1: admin
Password for server1: 
Welcome to bolt v1.0.0
Update available: version 1.0.1, run 'update' to see more info.
0 Sandboxes running | Host Info: 0.0% CPU | 0.0% RAM | 0.0% STORAGE
bolt running for 00:00:01
[server1] $ create project project1
Created project: project1
[server1] $ open project project1
[server1/project1] $ create sandbox sandbox1
Created sandbox: sandbox1 from base image: debian:bullseye
[server1/project1] $ sandboxes
sandbox1 - debian:bullseye - Running for 00:00:02
[server1/project1] $ open sandbox sandbox1
[project1/sandbox1] $ info
sandbox1 - debian:bullseye - Running for 00:00:02
0.0% CPU | 0.0% RAM | 0.0% STORAGE
Port mappings: {}
Reverse port mappings: {}
[project1/sandbox1] $ forward 10001 80
Port 10001 forwarded to 80
[project1/sandbox1] $ reverse 8080 10002
Port 8080 forwarded to host 10002
[project1/sandbox1] $ resources 50000 256
Resource limits updated: CPU quota 50000us, memory limit 256MB
[project1/sandbox1] $ shell
Enter token: <token_from_server>
Bolt Shell
[sandbox1/shell] $ echo hi
hi
[sandbox1/shell] $ exit
[project1/sandbox1] $ remove_forward 10001
Port forwarding for 10001 removed
[project1/sandbox1] $ delete sandbox sandbox1
Deleted sandbox: sandbox1
[project1/sandbox1] $ exit
[server1/project1] $ delete project project1
Deleted project: project1
[server1] $ config newadmin newpass
Configuration updated successfully
[server1] $ exit

Security Considerations

  • HTTPS: The CLI connects to the server over HTTPS but disables certificate verification for self-signed certificates. In production, ensure the server uses a trusted certificate.
  • Shell Authentication: The shell requires a server-provided token, valid for 1 hour.
  • Config Security: The ~/.bolt/config.json file is stored with 0600 permissions to protect credentials.
  • Input Sanitization: All inputs are sanitized to prevent injection attacks.

Troubleshooting

  • Connection Issues: Ensure the server is running and accessible on port 5000. Check firewall settings.
  • Authentication Errors: Verify credentials in ~/.bolt/config.json or provide correct ones when prompted.
  • Shell Issues: Ensure the token is correct and the shell port (20001–25000) is open.
  • Certificate Warnings: If using a self-signed certificate, the CLI disables verification. Update the server to use a trusted certificate for production.