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

• ALWAYS check deductibility rules BEFORE creating any document. See "Accounting Rules for Spain" section below.
• 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. Since holdedcli validates against Holded's schema (which doesn't include isReceipt), you must use --skip-validation flag.
• 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:

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, and use --skip-validation flag.
5. Request mandatory confirmation.
6. Run the command after confirmation.
7. Report result (status_code, affected ID, API response).

Base Commands

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:

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

Purchase receipt rule (mandatory for purchase tickets):

holded actions describe invoice.create-document --json
holded actions run invoice.create-document \
  --path docType=purchase \
  --body '{"isReceipt": true, "date": 1770764400, "contactId": "<contactId>", "items": [{"name": "Description", "units": 1, "subtotal": 29.4, "tax": 0}]}' \
  --skip-validation \
  --json

Important notes:

• Use --skip-validation flag because holdedcli validates against Holded's schema which doesn't include isReceipt.
• Use subtotal in items (not price) - this is the field name Holded's API expects.
• Timestamps must be in seconds (Unix epoch) and in Europe/Madrid timezone.

Timestamp calculation (Python):

from datetime import datetime, timezone, timedelta
# For 11/02/2026 00:00 in Madrid:
dt = datetime(2026, 2, 11, 0, 0, 0, tzinfo=timezone(timedelta(hours=1)))
print(int(dt.timestamp()))  # 1770764400

Accounting Rules for Spain

⚠️ ALWAYS check these rules BEFORE creating any expense document:

Before creating any document, ALWAYS verify:

1. Is the expense tax deductible?
2. Is the IVA deductible? (usually NO for restaurants, displacement)
3. If in doubt, ASK before creating the document.

Common mistake to avoid: Never set tax: 10 or tax: 21 for restaurant expenses - IVA is NOT deductible for meals unless it's a business event with proper justification.

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