Apploud CLI

A powerful command-line tool for interacting with the Apploud container hosting service. Manage your LXD/LXC containers with ease through an intuitive CLI interface.

Features

• 🚀 Interactive Shell Access: Connect directly to your containers with full terminal support
• 📁 File Transfer: Upload and download files with progress tracking
• 📊 Instance Management: List and monitor container status with colored indicators
• 🔐 Secure Authentication: Dual authentication support - GitHub OAuth or email/password
• 🎨 Enhanced UX: Beautiful ASCII art welcome messages and colored output
• 📝 Comprehensive Logging: Debug mode for troubleshooting
• 🔄 Real-time Operations: WebSocket-based communication for fast responses

Installation

Global Installation (Recommended)

npm install -g apploud-cli

After installation, you can use the apploud command from anywhere on your system.

Local Installation

npm install apploud-cli

With local installation, you'll need to use the CLI through npx:

npx apploud-cli <command>

Quick Start

1. Install the CLI globally:

   npm install -g apploud-cli

2. Authenticate with your Apploud account:

   # GitHub OAuth (recommended)
   apploud login
      
   # Or email/password
   apploud login --email

3. List your available instances:

   apploud instances

4. Connect to a container:

   apploud shell my-container

Configuration

The CLI connects to Apploud services using predefined URLs. You can override these with environment variables if needed:

• APP_URL: The base URL of the Apploud API
• WS_URL: The WebSocket URL for real-time operations

Commands Reference

Authentication Commands

login

Log in to the Apploud system and store authentication token. The CLI supports two authentication methods:

Method 1: GitHub OAuth (Recommended)

apploud login

This will:

1. Open your default browser
2. Redirect you to GitHub for OAuth authentication
3. Store your authentication token securely for future use

Method 2: Email and Password

apploud login --email

This will:

1. Prompt you to enter your email address
2. Prompt you to enter your password
3. Authenticate directly with the Apploud service
4. Store your authentication token securely for future use

Options:

• --email: Use email/password authentication instead of GitHub OAuth

logout

Log out and remove stored authentication token.

apploud logout

Instance Management Commands

instances

List all available container instances with status indicators.

apploud instances

Features:

• Colored status indicators (🟢 Running, 🔴 Stopped, 🟡 Other states)
• Clean tabular format
• Real-time status information

status

Check the overall status of the LXD server and connection.

apploud status

shell <instanceName>

Start an interactive shell session with the specified container.

apploud shell my-container
apploud shell web-server-01

Features:

• Full terminal emulation with xterm support
• Real-time bidirectional communication
• Automatic fallback to exec mode if shell fails
• Proper signal handling and cleanup

Alias: ssh (hidden from help but functional for convenience)

File Transfer Commands

push <filePath> <instanceName> <destinationPath>

Upload a file or directory to a container.

# Upload a single file
apploud push ./config.json my-container /etc/app/config.json

# Upload to a directory (preserves filename)
apploud push ./app.log my-container /var/log/

# Upload with recursive flag for directories
apploud push ./my-app my-container /opt/ --recursive

Options:

• -r, --recursive: Recursively upload directories

Features:

• Progress tracking for large files
• Automatic directory creation
• Original filename preservation
• Binary file support

pull <instanceName> <filePath> <destinationPath>

Download a file from a container to your local system.

# Download to current directory
apploud pull my-container /var/log/app.log ./

# Download to specific file
apploud pull my-container /etc/nginx/nginx.conf ./nginx-backup.conf

# Download to directory (preserves original filename)
apploud pull my-container /var/log/app.log ./logs/

Options:

• -r, --recursive: Recursively download directories

Features:

• Automatic file size detection
• Progress indicators
• Original filename preservation
• Support for various destination formats (., ./, absolute paths)

System Commands

--version

Display the current version of the CLI.

apploud --version

--help

Show comprehensive help information.

apploud --help
apploud <command> --help  # Command-specific help

Troubleshooting

Common Issues

Authentication failures

• Run apploud logout followed by apploud login (or apploud login --email)
• For GitHub OAuth: Check if your GitHub account has access to the Apploud service
• For email/password: Verify your credentials are correct

Connection issues

• Check if your Apploud server is running and accessible
• Verify your network connection

File transfer issues

• Ensure you have sufficient permissions on both local and remote systems
• Check available disk space

Getting Help

1. Run commands with --help for detailed usage information
2. Check the GitHub repository for known issues

Contributing

We welcome contributions! Please see our GitHub repository for:

• Reporting bugs
• Suggesting features
• Submitting pull requests

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a detailed list of changes and version history.