Remote execution CLI for deployment
npm install remote-deploy-cli> A lightweight, secure Node.js CLI tool for remote execution using a Client-Server architecture. Designed to simplify deployment workflows by triggering commands (like Docker Compose) on remote servers securely.
Last Updated: 2026-01-17
- Description
- Architecture Overview
- Installation
- Client Commands
- deploy
- Client Configuration
- Server Commands
- listen
- start (Background)
- Server Configuration
- Command Interactions
- Configuration Reference
- Troubleshooting
- License
---
redep allows you to securely trigger deployment scripts on a remote server from your local machine or CI/CD pipeline.
1. Server (Remote Machine): Runs the listener process (redep listen). It waits for authenticated HTTP requests and executes local shell commands (e.g., docker compose up).
2. Client (Local Machine/CI): Sends commands (redep deploy) to the Server URL.
---
To use redep as a command-line tool anywhere on your system:
``bash`
npm install -g remote-deploy-cli
If you prefer to use it within a specific project (e.g., via npm scripts):
`bash`
npm install remote-deploy-cli --save-dev
---
These commands are executed on your local machine or CI/CD runner.
Triggers a deployment on the remote server.
Syntax:
`bash`
redep deploy
Parameters:
- : The service type to deploy.fe
- : Frontend (pre-configured to run docker compose pull && docker compose up -d).custom
- : Custom command (configured on server via deployment_command).
Requirements:
- SERVER_URL must be configured.SECRET_KEY
- must match the server's key.
Example:
`bashDeploy frontend service
redep deploy fe
Expected Output:
`
[INFO] Deploying fe to http://192.168.1.50:3000...
[SUCCESS] Deployment triggered successfully.
`$3
Configure the client to know where the server is.
`bash
Set Server URL
redep config set server_url http://:3000Set Secret Key
redep config set secret_key my-secret-key
`---
Server Commands
These commands are executed on the remote server (VPS, VM, etc.).
$3
Starts the server in the foreground. Useful for debugging or running inside Docker.
Syntax:
`bash
redep listen [--port ]
`Options:
-
-p, --port: Specify port (default: 3000).Example:
`bash
redep listen --port 4000
`$3
Starts the server in background mode (Daemon).
- Auto-PM2: If
pm2 is installed, it uses PM2 for process management.
- Native Fallback: If pm2 is missing, it uses Node.js child_process to detach.Syntax:
`bash
redep start [--port ]
`Related Commands:
-
redep stop: Stops the background server.
- redep status: Checks if the server is running.Example:
`bash
redep start
[SUCCESS] Server started in background using PM2
`$3
Configure the runtime environment for the server.
`bash
Set Working Directory (Where docker-compose.yml lives)
redep config set working_dir /path/to/projectSet Secret Key
redep config set secret_key my-secret-keySet Custom Deployment Command (Optional)
redep config set deployment_command "git pull && npm install && pm2 restart app"
`#### Running with Docker (Recommended)
Instead of manual configuration, run the server as a container:
`yaml
docker-compose.server.yml
services:
deploy-server:
image: remote-deploy-cli
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./my-app:/workspace
environment:
- WORKING_DIR=/workspace
- SECRET_KEY=secure-key
- DEPLOYMENT_COMMAND=docker compose restart app
`---
$3
Helper to generate configuration values.
-
generate secret_key: Generates a secure 32-character secret key and saves it to config.
- generate working_dir: Sets the current directory as the working_dir.$3
Interactive initialization for configuration.
-
init client: Prompts for server_url and secret_key.
- init server: Prompts for server_port, working_dir, deployment_command, and secret_key (auto-generates if empty).Command Interactions
$3
`mermaid
sequenceDiagram
participant Client (CI/Local)
participant Server (Remote) Note over Client: User runs "redep deploy fe"
Client->>Client: Read Config (URL, Secret)
Client->>Server: POST /deploy { type: "fe" } (Auth: Bearer Token)
Note over Server: Verify Secret Key
alt Invalid Key
Server-->>Client: 403 Forbidden
Client->>User: Error: Authentication Failed
else Valid Key
Server->>Server: Execute "docker compose up" in WORKING_DIR
Server-->>Client: 200 OK { status: "success" }
Client->>User: Success Message
end
`---
Configuration Reference
| Config Key | Env Variable | Description | Context |
| :------------------- | :------------------- | :----------------------------------------------- | :--------- |
|
server_port | SERVER_PORT | Port for the server to listen on (Default: 3000) | Server |
| working_dir | WORKING_DIR | Directory to execute commands in | Server |
| deployment_command | DEPLOYMENT_COMMAND | Custom command for deploy custom | Server |
| server_url | SERVER_URL | URL of the remote redep server | Client |
| secret_key | SECRET_KEY | Shared secret for authentication | Both |---
Troubleshooting
$3
- Context: Server
- Fix: Run
redep config set working_dir /path or check docker-compose.yml environment.$3
- Context: Client
- Fix: Ensure server is running (
redep status or docker ps) and port 3000 is open.$3
- Context: Client
- Fix: Re-check
SECRET_KEY` on both machines. They must match exactly.---
ISC © 2026