# Holded Skill

> Operate Holded ERP through holdedcli to read and update data safely. Use when the user asks to read, search, create, update, or delete Holded entities (contacts, invoices, products, CRM, projects, team, accounting) or run Holded API endpoints from the terminal.

- Skill: `jaumecornado/holded-skill` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jaumecornado/holded-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jaumecornado/holded-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- Author: jaumecornado (https://skillmd.com/u/jaumecornado)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jaumecornado/holded-skill

---


# holded-skill

Use `holdedcli` to read and modify Holded data with a safe, repeatable workflow.

## Operational Flow

1. Confirm technical prerequisites.
2. Discover available actions with `holded actions list`.
3. Inspect the selected action with `holded actions describe <action> --json`.
4. Classify the action as read or write.
5. If it is a write operation, ask for explicit confirmation before execution.
6. Run with `--json` and summarize IDs, HTTP status, and applied changes.

## Prerequisites

- Verify that the binary exists: `holded help`
- Verify credentials: `holded auth status` or `HOLDED_API_KEY`
- Prefer structured output whenever possible: `--json`

## Safety Rules

- Treat any `POST`, `PUT`, `PATCH`, or `DELETE` action as **write**.
- Treat any `GET` action (or `HEAD` when present) as **read**.
- Before any operation, always run `holded actions describe <action> --json` (after `holded actions list`) to validate accepted parameters.
- For purchase receipts, always enforce `docType=purchase` and include `"isReceipt": true` in the JSON body.
- Ask for explicit user confirmation **every time** before any write action.
- Do not execute writes on ambiguous replies (`ok`, `go ahead`, `continue`) without clarification.
- Repeat the exact command before confirmation to avoid unintended changes.
- If the user does not confirm, stop and offer payload adjustments.

## Mandatory Confirmation Protocol

Before any write action, show:

1. Holded action (`action_id` or `operation_id`).
2. Method and endpoint.
3. `--path`, `--query`, and body parameters (`--body` or `--body-file`).
4. The exact command to run.

Use this format:

```text
This operation will modify data in Holded.
Action: <action_id> (<METHOD> <endpoint>)
Changes: <short summary>
Command: holded actions run ... --json
Do you confirm that I should run exactly this command? (reply with "yes" or "confirm")
```

Execute only after an explicit affirmative response.

## Execution Pattern

### Read Operations

1. Locate the action with `holded actions list --json` (use `--filter`).
2. Verify accepted path/query/body parameters with `holded actions describe <action> --json`.
3. Run `holded actions run <action> ... --json`.
4. Return a clear summary and relevant IDs for follow-up steps.

### Write Operations

1. Locate and validate the action.
2. Run `holded actions describe <action> --json` to verify required/optional parameters.
3. Prepare the final payload.
4. If creating a purchase receipt/ticket, verify `docType=purchase` and `"isReceipt": true`.
5. Request mandatory confirmation.
6. Run the command after confirmation.
7. Report result (`status_code`, affected ID, API response).

## Base Commands

```bash
holded auth set --api-key "$HOLDED_API_KEY"
holded auth status
holded ping --json
holded actions list --json
holded actions list --filter contacts --json
holded actions describe invoice.get-contact --json
holded actions run invoice.get-contact --path contactId=<id> --json
```

For long payloads, prefer `--body-file`:

```bash
holded actions run invoice.update-contact \
  --path contactId=<id> \
  --body-file payload.json \
  --json
```

Purchase receipt rule (mandatory for purchase tickets):

```bash
holded actions describe invoice.create-document --json
holded actions run invoice.create-document \
  --path docType=purchase \
  --body '{"isReceipt": true}' \
  --json
```

## Error Handling

- If `MISSING_API_KEY` appears, configure API key through `--api-key`, `HOLDED_API_KEY`, or `holded auth set`.
- If `ACTION_NOT_FOUND` appears, list the catalog and search with `--filter`.
- If `INVALID_BODY` appears, validate JSON before execution.
- If `API_ERROR` appears, report `status_code` and the API snippet.

## References

- Read `{baseDir}/references/holdedcli-reference.md` for quick commands and criteria.
- Use dynamic action discovery and parameter inspection via:
  - `holded actions list --json`
  - `holded actions describe <action> --json`