homelab-cli

A command-line tool for self-hosting utilities and deployment automation. Currently supports triggering deployments for Dokploy applications.

Installation

Install globally via npm:

npm install -g @raulfdm/homelab-cli

Or use with npx (no installation required):

npx @raulfdm/homelab-cli --help

Usage

Trigger Dokploy Deployment

The primary feature is triggering deployments for Dokploy applications. You can provide configuration through environment variables, CLI flags, or a combination of both.

Using Environment Variables

# Set environment variables
export DOKPLOY_SERVER_DOMAIN="https://your-dokploy-server.com"
export DOKPLOY_API_KEY="your-api-key"
export DOKPLOY_APP_ID="your-application-id"

# Trigger deployment
homelab deploy trigger

Using CLI Flags

homelab deploy trigger \
  --app-id "your-application-id" \
  --server-domain "https://your-dokploy-server.com" \
  --api-key "your-api-key"

Mixed Approach (CLI flags override environment variables)

# Use env vars for sensitive data, flags for app-specific values
export DOKPLOY_API_KEY="your-api-key"
homelab deploy trigger \
  --app-id "your-application-id" \
  --server-domain "https://your-dokploy-server.com"

Available Commands

• deploy trigger: Trigger a deployment for a Dokploy application
• --help: Show help information for any command

Configuration Options

| CLI Flag | Environment Variable | Description | Required | | ----------------- | ----------------------- | ------------------------ | -------- | | --app-id | DOKPLOY_APP_ID | Application ID to deploy | ✅ | | --server-domain | DOKPLOY_SERVER_DOMAIN | Dokploy server URL | ✅ | | --api-key | DOKPLOY_API_KEY | Dokploy API key | ✅ |

Development

Prerequisites

• Bun v1.3.6 or higher
• Node.js (for runtime compatibility)

Setup

1. Clone the repository:

   git clone <repository-url>
   cd sh-cli

2. Install dependencies:

   bun install

Development Workflow

Running locally during development

# Run the CLI directly with Bun
bun run src/cli.ts --help

# Example: Test deploy command
bun run src/cli.ts deploy --help

# Example: Test trigger deployment command
bun run src/cli.ts deploy trigger --help

Building the project

# Build for distribution
bun run build

This will compile the TypeScript source to the dist/ directory.

Code formatting

# Format code
bun run fmt

# Check formatting without modifying files
bun run fmt:check

Testing your changes

1. Build the project: bun run build
2. Test the built version: node bin/run.js --help
3. Or install globally for testing: npm install -g .

Project Structure

sh-cli/
├── bin/
│   └── run.js               # Entry point for the published CLI
├── src/
│   ├── cli.ts               # Main CLI interface
│   └── modules/
│       └── deploy/
│           ├── index.ts     # Deploy command module
│           └── trigger.ts   # Deployment trigger functionality
├── dist/                    # Built JavaScript files (generated)
├── package.json            # Package configuration
└── README.md              # This file

Adding New Commands

1. Create a new module in src/modules/
2. Import and integrate it in src/cli.ts
3. Update the CLI help text and flags as needed
4. Add tests and documentation

Publishing

This project uses Changesets for version management:

# Add a changeset (describes your changes)
npx changeset

# Version packages (updates version and changelog)
npx changeset version

# Publish to npm
npm publish

The build process runs automatically before publishing via the prepublish script.