zoho-cli

Interactive CLI for staging and pushing items to Zoho Projects.

Collect tasks, bugs and milestones locally, review them, then push to Zoho in one go.

Features

• Interactive wizard and batch mode for creating tasks, bugs & milestones
• Local staging area - review and approve items before pushing
• OAuth 2.0 Self Client flow (grant token → refresh token → access token)
• Zoho Projects API V3 (EU/US/IN/AU) with V2 fallback for bugs & documents
• Built-in rate limiting (95 req / 2 min) and retry with backoff
• Advisory file locking on the local store
• Lock/unlock mechanism to prevent accidental writes
• Default user identity for auto-filling person_responsible
• Credentials via config file or environment variables

Installation

go install github.com/Tristram1337/zoho-cli@latest

Or build from source:

git clone https://github.com/Tristram1337/zoho-cli.git
cd zoho-cli
go build -o zoho-cli .

Setup

1. Create a Self Client

Go to Zoho API Console → Self Client → note your Client ID and Client Secret.

2. Generate a Grant Token

In the Self Client panel, set scope:

ZohoProjects.portals.READ,ZohoProjects.projects.ALL,ZohoProjects.tasks.ALL,ZohoProjects.bugs.ALL,ZohoProjects.milestones.ALL,ZohoProjects.documents.ALL

Generate a grant token (valid ~1 min).

3. Exchange for Refresh Token

curl -X POST "https://accounts.zoho.eu/oauth/v2/token" \
  -d "grant_type=authorization_code&client_id=YOUR_ID&client_secret=YOUR_SECRET&code=GRANT_TOKEN"

Save the refresh_token from the response.

4. Run init

zoho-cli init

The wizard asks for Client ID, Client Secret, and Refresh Token, tests the connection, and saves config to ~/.config/zoho-cli/config.yaml.

Environment Variables

Instead of (or in addition to) the config file, you can set:

Variable	Description
ZOHO_CLIENT_ID	OAuth Client ID
ZOHO_CLIENT_SECRET	OAuth Client Secret
ZOHO_REFRESH_TOKEN	OAuth Refresh Token
ZOHO_PORTAL_ID	Portal ID

Environment variables override config file values.

Usage

# Interactive mode (menu-driven)
zoho-cli interactive    # or: zoho-cli i

# Add items
zoho-cli add            # interactive wizard

# Review & approve
zoho-cli list           # show all staged items
zoho-cli list all       # including already pushed
zoho-cli review         # mark items as ready / skip / edit

# Push to Zoho
zoho-cli push           # push all ready items
zoho-cli push --dry-run # preview without pushing

# Other
zoho-cli status         # summary of staged items
zoho-cli edit           # edit a staged item
zoho-cli delete         # remove a staged item
zoho-cli config         # show current config
zoho-cli whoami         # show default user
zoho-cli set-user       # set default user from Zoho
zoho-cli lock           # lock CLI (prevent writes)
zoho-cli unlock         # unlock permanently
zoho-cli unlock 30      # unlock for 30 minutes

Commands

Command	Description
init	Setup wizard: configure portal & tokens
add	Stage a new task / bug / milestone
list	Show all staged items
review	Interactively approve staged items
push	Push approved items to Zoho Projects
edit	Edit a staged item
delete	Remove a staged item
status	Show staging summary
interactive	Menu-driven mode
config	Display current configuration
whoami	Show default user identity
set-user	Pick default user from Zoho
lock	Lock write commands
unlock	Unlock CLI, optionally for N minutes

Configuration

Config lives at ~/.config/zoho-cli/config.yaml. See config.example.yaml for the format.

Local staging data is stored in ~/.config/zoho-cli/store.json.

License

MIT. Copyright (c) 2026 Tristram1337.