🛡️ Complete Organization Configuration & Opt-in Accounting Execution

zbooks provides 100% full coverage of the Zoho Books V3 API surface, enabling complete organization metadata extraction, module preference updates, field schema inspection, automation management, and live Deluge script execution.

Read operations (pull, settings, fn list, invoice list) query your accounting data safely, while update commands (settings pref-update, fn create/update/test, invoice create/send) execute real REST API payloads against your chosen active Zoho Books organization.

🚀 Quick Start

# 1. Install globally
npm install -g wanas-zbooks-cli

# 2. Authenticate (Browser-based OAuth login on port 14890)
zbooks login

# 3. Pull complete organization metadata into Books/[OrgName]_[OrgID]
zbooks pull

# 4. Create and test a Deluge Custom Function live from a local .ds file
zbooks fn create --name "process_invoice" --entity invoice --script-file "./my_script.ds"
zbooks fn test 2715275000020459017 2715275000020479026

# 5. Inspect or update module preferences & accounting settings
zbooks settings pref invoices
zbooks settings accountant
zbooks settings customfields

# 6. Call ANY Zoho Books V3 REST endpoint directly
zbooks api GET /invoices

💡 Prefer not to install globally? Use npx wanas-zbooks-cli <command> instead.

🌟 Key Features

📋 CLI Commands Reference

Configures or clears your local Zoho Books OAuth session and active Data Center domain.

# Interactive browser OAuth login on http://localhost:14890/zoho/callback
zbooks login

# Sign in with custom Client ID & Secret
zbooks login --dc eu --client-id <id> --client-secret <secret>

# Clear local session
zbooks logout

Extract 100% of an organization's configuration into version-controlled JSON project files under Books/[OrgName]_[OrgID].

# Pull active organization metadata
zbooks pull

# Clean output folder before pulling
zbooks pull --clean

# Extract to a custom output directory
zbooks pull -o ./metadata

Develop, deploy, update, and test Deluge custom functions directly from local files.

# List all custom functions
zbooks fn list

# Get script content and details by ID
zbooks fn get 2715275000020459017

# Create a custom function from a local .ds file
zbooks fn create --name "my_function" --entity invoice --script-file "./my_script.ds"

# Update custom function from a local file
zbooks fn update 2715275000020459017 --script-file "./my_script.ds"

# Test & execute Deluge function live against a sample invoice ID
zbooks fn test 2715275000020459017 2715275000020479026

Inspect and update accounting preferences, field capacity limits, accountant lock dates, system accounts, and approval rules.

# View invoice preferences
zbooks settings pref invoices

# View accountant settings (closing dates, lock dates, accounting basis)
zbooks settings accountant

# View standard AR/AP system accounts configuration
zbooks settings system-accounts

# Inspect field schemas and capacity limits per data type for contacts or invoices
zbooks settings fields invoice

# List workflow automation rules, webhooks & custom triggers
zbooks settings workflows
zbooks settings webhooks
zbooks settings fieldupdates

# Inspect API usage report & top endpoints
zbooks settings api-usage

Manage business records directly from the terminal.

# List invoices, contacts, items
zbooks invoice list --status unpaid
zbooks contact list --type customer
zbooks item list

# Create a new contact or item
zbooks contact create --data '{"contact_name":"Acme Corp","contact_type":"customer"}'
zbooks item create --data '{"name":"Consulting Service","rate":150}'

# Send or void an invoice
zbooks invoice send 460000000055555
zbooks invoice void 460000000055555

# View Chart of Accounts
zbooks coa list

Call ANY Zoho Books REST API endpoint dynamically with query parameters and JSON payloads.

# GET endpoint
zbooks api GET /invoices --params '{"status":"unpaid"}'

# POST endpoint
zbooks api POST /projects --data '{"project_name":"ERP Setup","customer_id":"460000000012345"}'

🌐 Data Center Support

| Data Center | Domain Suffix | API Base URL | | :--- | :--- | :--- | | United States (US) | com | https://www.zohoapis.com/books/v3 | | Europe (EU) | eu | https://www.zohoapis.eu/books/v3 | | India (IN) | in | https://www.zohoapis.in/books/v3 | | Australia (AU) | com.au | https://www.zohoapis.com.au/books/v3 | | Canada (CA) | ca | https://www.zohoapis.ca/books/v3 | | Saudi Arabia (SA) | sa | https://www.zohoapis.sa/books/v3 |

📄 License

ISC © Wanas Apps