holded-skill

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

Operational Flow

1. 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: INLINECODE4
• Verify credentials: holded auth status or INLINECODE6
• Prefer structured output whenever possible: INLINECODE7

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. 1. Holded action (action_id or operation_id).
2. Method and endpoint.
3. INLINECODE25, --query, and body parameters (--body or --body-file).
4. The exact command to run.

Use this format:

CODEBLOCK0

Execute only after an explicit affirmative response.

Execution Pattern

Read Operations

1. 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. 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

CODEBLOCK1

For long payloads, prefer --body-file:

CODEBLOCK2

Purchase receipt rule (mandatory for purchase tickets):

CODEBLOCK3

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):
CODEBLOCK4

Accounting Rules for Spain

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

Before creating any document, ALWAYS verify:

1. 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: