---
name: dokploy
description: Operates Dokploy through CLI or API for projects, environments, applications, databases, deployments, and infrastructure workflows. Use when the user mentions Dokploy, deploying to Dokploy, dokploy CLI/API, environment variable sync, or managing Dokploy resources.
enabled: false
source: github:JuanJoseGonGi/skills
imported-from: github:JuanJoseGonGi/skills
---

# Dokploy Operations

Use this skill to manage Dokploy with a CLI-first workflow and an API fallback when commands are unavailable or insufficient.

## Skill Contents

- `SKILL.md`: Routing, safety rules, and end-to-end workflows.
- `references/cli.md`: Command map and non-interactive command examples.
- `references/api.md`: Endpoint map and curl examples for OpenAPI and tRPC styles.
- `scripts/dokploy_api.py`: Safer API helper with retries, dry-run mode, and endpoint-style fallback.
- `scripts/stop_app.sh`: Wrapper for `application.stop` incident action.
- `scripts/rollback.sh`: Wrapper for `rollback.rollback` incident action.
- `scripts/kill_deployment.sh`: Wrapper for `deployment.killProcess` incident action.
- `references/operator-playbook.md`: Incident workflow for stop, rollback, and stuck-deployment recovery.

## When to Use

Use this skill when users ask to:

- Deploy to Dokploy.
- Create or manage Dokploy projects, environments, applications, or databases.
- Pull or push environment variables for Dokploy services.
- Trigger deployments, stop services, or remove resources.
- Operate Dokploy via API instead of the CLI.

## Preconditions

Before performing any mutation, verify all of the following:

1. Dokploy base URL is known, for example `https://dokploy.example.com`.
2. API key/token is available from Dokploy profile settings.
3. The target project/environment/resource is identified by ID, not only by name.
4. A non-destructive list/read command has been run first.

Never print secrets in logs or commit them to files.

## Execution Routing

1. Prefer CLI when `dokploy` is installed and command coverage is sufficient.
2. Use API when:
   - CLI is not installed.
   - The action is not exposed in CLI.
   - Bulk automation or scriptable JSON output is needed.
3. If an API request fails due to endpoint style mismatch, switch between:
   - OpenAPI style: `/api/<resource>.<action>`
   - tRPC style: `/api/trpc/<resource>.<action>`

See `references/api.md` for payload differences.

## Safer API Helper

Use the bundled helper for API calls that need:

- Automatic style fallback (`openapi` then `trpc`, or the reverse).
- Retries for transient failures.
- Dry-run preview before execution.
- Destructive-action guardrails (`--yes` required).

Examples:

- Read call:
  - `python3 skills/dokploy/scripts/dokploy_api.py project.all --style auto`
- Mutating call (requires confirmation flag):
  - `python3 skills/dokploy/scripts/dokploy_api.py application.stop --method POST --json '{"applicationId":"<applicationId>"}' --yes`
- Dry run first:
  - `python3 skills/dokploy/scripts/dokploy_api.py application.stop --method POST --json '{"applicationId":"<applicationId>"}' --dry-run`

## Standard Workflow

### 1) Connectivity and Auth

- CLI path:
  - Install: `npm install -g @dokploy/cli`
  - Authenticate: `dokploy authenticate --url "$DOKPLOY_URL" --token "$DOKPLOY_AUTH_TOKEN"`
  - Verify: `dokploy verify`
- API path:
  - Smoke test: `curl -sS "$DOKPLOY_URL/api/project.all" -H "x-api-key: $DOKPLOY_AUTH_TOKEN"`

### 2) Inventory First

- List projects, then inspect target project.
- Resolve environment IDs before app or database actions.
- Resolve application/database IDs before deploy/stop/delete actions.

### 3) Execute the Requested Change

- For project, environment, app, and database CRUD/deploy operations, prefer CLI.
- For advanced operations (deployment process control, container introspection, server-level actions), use API when needed.

### 4) Verify Outcome

- Re-read the mutated resource.
- Check deployment status where relevant.
- Confirm resulting state matches the user request.

## High-Value Workflows

### Deploy an application

1. Resolve `projectId`, `environmentId`, and `applicationId`.
2. Trigger deploy via CLI: `dokploy app deploy --applicationId <id> --skipConfirm`
3. Fallback API: `POST /api/application.deploy` with `applicationId`.
4. Verify by querying deployment/application status.

### Create full app path

1. Create project.
2. Create environment within project.
3. Create application within environment.
4. Configure source/build settings if needed.
5. Deploy and verify.

### Manage database lifecycle

1. Create the database service in the target environment.
2. Deploy/start/stop based on requested state.
3. Save env changes only through secure channels.
4. Verify with resource fetch after each mutation.

### Handle incidents (stop, rollback, kill)

Use `references/operator-playbook.md` for response-ready workflows:

1. Stop impacted application or database service.
2. Kill stuck deployment process when queues are blocked.
3. Execute rollback using a verified `rollbackId`.
4. Re-verify state and service health.

Quick wrappers for common incident commands:

- Stop app: `bash skills/dokploy/scripts/stop_app.sh <applicationId> --dry-run` then `--yes`
- Rollback: `bash skills/dokploy/scripts/rollback.sh <rollbackId> --dry-run` then `--yes`
- Kill stuck deployment: `bash skills/dokploy/scripts/kill_deployment.sh <deploymentId> --dry-run` then `--yes`

### Synchronize environment variables

1. Pull to local file first.
2. Review intended diff.
3. Push with explicit confirmation.
4. Redeploy service if required by runtime behavior.

## Safety Rules

- Always run a read/list operation before destructive commands.
- Confirm delete operations explicitly unless user requested forceful automation.
- Avoid storing API keys in tracked files.
- Do not expose credentials in responses, logs, screenshots, or command history snippets.
- For production targets, favor staged rollout and post-change verification.

## Common Pitfalls

- Command naming drifts across versions. Run `dokploy --help` and scoped help before assuming syntax.
- Some docs show space-based commands while older tooling may expose colon-style forms.
- API endpoint style can differ by server version (`/api/*` vs `/api/trpc/*`).
- API responses can be nested (`result.data.json`) in tRPC mode.

## References

- CLI commands and flags: `references/cli.md`
- API endpoints and payloads: `references/api.md`
- Incident actions: `references/operator-playbook.md`
- Official Dokploy docs: `https://docs.dokploy.com/docs/cli` and `https://docs.dokploy.com/docs/api`