Skip to content

README.md

Latest commit

 

History

History
136 lines (98 loc) · 3.9 KB

README.md

File metadata and controls

136 lines (98 loc) · 3.9 KB
Raw

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.