open-index/open-npm huggingface dataset:
npm package: @surgedev/agent
Description: SurgeDev deployment agent — runs on target VPS, polls for tasks and executes docker compose
Author: SurgeDev
Latest version: 0.0.2

# @surgedev/agent

Runs on your VPS, polls the SurgeDev control plane for deployment tasks, and executes `docker build` / `docker compose`.

## Requirements

- Node.js **18+**
- Docker Engine with **Compose v2** (`docker compose`)

## Install

```bash
npm install -g @surgedev/agent
```

## Configure

Set environment variables (e.g. in systemd `EnvironmentFile`):

| Variable | Required | Description |
|----------|----------|-------------|
| `SURGEDEV_API_URL` | Yes | Control plane base URL (no trailing `/`) |
| `SURGEDEV_HOST_ID` | Yes | Host UUID from platform admin registration |
| `SURGEDEV_AGENT_TOKEN` | Yes | Agent token (`sat_...`) from registration |
| `SURGEDEV_POLL_INTERVAL` | No | Poll interval in seconds (default: `10`) |
| `SURGEDEV_WORK_DIR` | No | Working directory (default: `/opt/surgedev`) |

## Run

```bash
surgedev-agent
```

## License

Apache-2.0
npm package: @surgedev/cli
Description: SurgeDev CLI — Manage your SurgeDev backend from the command line (database, storage, auth)
Author: SurgeDev
Latest version: 0.0.4

# SurgeDev CLI

> Manage your SurgeDev backend from the command line — database, storage, auth, all in one tool.

## Install

```bash
npm install -g surgedev-cli
```

## Quick Start

```bash
# 1. Set your API credentials
export SURGEDEV_API_URL=http://localhost:7130
export SURGEDEV_API_KEY=ik_xxx

# 2. Test the connection
surgedev ping

# Or use a .env file in your project root
echo "SURGEDEV_API_URL=http://localhost:7130" >> .env
echo "SURGEDEV_API_KEY=ik_xxx" >> .env
```

## Commands

### Database

```bash
surgedev db list                              # List all tables
surgedev db schema <table>                    # Show table structure
surgedev db create <table> --columns '[...]'  # Create a table
surgedev db drop <table>                      # Drop a table
surgedev db query <table>                     # Query records
surgedev db insert <table> --data '[...]'     # Insert records
surgedev db update <table> --filter '{}' --data '{}'  # Update records
surgedev db delete <table> --filter '{}'      # Delete records
surgedev db sql "SELECT * FROM users"         # Run raw SQL
```

**Query with filters (PostgREST style):**

```bash
surgedev db query users --filter '{"age":"gt.18","status":"eq.active"}' --select id,name --limit 10
```

**Create a table:**

```bash
surgedev db create posts --columns '[
  {"name": "title", "type": "string", "nullable": false},
  {"name": "content", "type": "text"},
  {"name": "published", "type": "boolean", "default": "false"}
]'
```

### Storage

```bash
surgedev storage ls                           # List all buckets
surgedev storage create <bucket>              # Create a bucket
surgedev storage create <bucket> --private    # Create a private bucket
surgedev storage drop <bucket>                # Delete a bucket
surgedev storage objects <bucket>             # List files in a bucket
```

### Auth

```bash
surgedev auth users                           # List registered users
surgedev auth users --search "alice"          # Search users
surgedev auth config                          # View auth configuration
```

### Utility

```bash
surgedev ping                                 # Test backend connection
```

## Configuration

| Environment Variable | Description | Default |
|---|---|---|
| `SURGEDEV_API_URL` | Backend API URL | `http://localhost:7130` |
| `SURGEDEV_API_KEY` | API Key (required) | — |

You can also place a `.env` file in your project root or the CLI's install directory.

## Use with AI Agents

SurgeDev CLI is designed to be used by AI coding agents (Cursor, Claude Code, etc.) via terminal. The AI runs CLI commands directly — no MCP protocol needed.

```
AI Agent → terminal → surgedev CLI → SurgeDev Backend API
```

## License

[Apache-2.0](./LICENSE)