Jinshan Calendar CLI

A powerful command-line interface for managing Jinshan (WPS) calendar events. This CLI tool allows you to create, list, remove, and schedule calendar events programmatically.

Features

• 🔐 Authentication Management: Secure cookie-based authentication
• 📅 Event Management: Create, list, and remove calendar events
• 🗓️ Batch Operations: Create multiple events with self-incrementing names
• 📊 Group Management: List and manage calendar groups
• ⏰ Flexible Scheduling: Support for date ranges and relative time periods
• 🔄 Recurring Events: Create events on specific weekdays with patterns

Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g jinshan-calendar

# Verify installation
jinshan-calendar --version

Option 2: Install from source

Prerequisites

• Node.js 18+ (recommended: Node.js 20+)
• npm or yarn

Setup

1. Clone or download the project

   git clone <repository-url>
   cd jinshan-calendar

2. Install dependencies

   npm install

3. Make the CLI executable

   chmod +x index.mjs

4. Use locally

   node index.mjs --help

Quick Start

1. Authentication Setup

First, you need to configure your authentication cookies:

# Set up your cookies (get them from your browser)
jinshan-calendar auth "your-cookie-string-here"

# Check your configured cookies
jinshan-calendar auth

How to get cookies:

1. Go to https://rili.wps.cn/
2. Open Developer Tools (F12)
3. Go to Network tab
4. Make any request (like clicking on a calendar)
5. Copy the cookie header from the request

2. List Your Calendar Groups

# List all your calendar groups
jinshan-calendar groups

3. Create Your First Event

# Create a simple event
jinshan-calendar event create --group 121972817 "Team Meeting" --startTime "2025-6-19 16:30:00"

Commands Reference

Authentication

# Set up cookies
jinshan-calendar auth "your-cookie-string"

# Check current cookies
jinshan-calendar auth

Groups

# List all calendar groups
jinshan-calendar groups

Events

List Events

# List all events for next 30 days
jinshan-calendar event list --days 30

# List events from specific group for next 7 days
jinshan-calendar event list --group 121972817 --days 7

# List events in date range
jinshan-calendar event list 2025-2-5 2025-3-6

# List events from specific group in date range
jinshan-calendar event list --group 121972817 2025-2-5 2025-3-6

Create Events

# Create event with explicit end time
jinshan-calendar event create --group 121972817 "Team Meeting" --startTime "2025-6-19 16:30:00" --endTime "2025-6-19 16:45:00"

# Create event with duration
jinshan-calendar event create --group 121972817 "Quick Call" --startTime "2025-6-19 16:30:00" --duration 30

# Create event with default 30-minute duration
jinshan-calendar event create --group 121972817 "Daily Standup" --startTime "2025-6-19 16:30:00"

Remove Events

# Remove single event
jinshan-calendar event remove 114610227

# Remove multiple events
jinshan-calendar event remove 114610227 114610228 114610229

Bulk Remove Events

# Remove events in date range
jinshan-calendar event removeAll --group 121972817 --startTime 2025-2-5 --endTime 2025-3-6

# Remove events for next 30 days from start date
jinshan-calendar event removeAll --group 121972817 --startTime 2025-6-19 --days 30

Schedule Recurring Events

# Version releases on Monday and Friday (all-day events with incrementing)
jinshan-calendar event schedule "Publish Version 1.$.0" 8 --group 121972817 --startTime "2025-6-19" --days 30 --weekDays 15

# Daily standup meetings Monday to Friday (60-minute timed events)
jinshan-calendar event schedule "Daily Standup" --group 121972817 --startTime "2025-6-19 09:00:00" --days 30 --weekDays 12345 --duration 60

# Weekly team meetings on Wednesday (all-day events with incrementing)
jinshan-calendar event schedule "Team Meeting Week $" --group 121972817 --startTime "2025-6-19" --endTime "2025-8-19" --weekDays 3

# Weekly review on Friday (all-day events, same name for all)
jinshan-calendar event schedule "Weekly Review" --group 121972817 --startTime "2025-6-19" --days 30 --weekDays 5

# Long workshops on Tuesday (2-hour timed events)
jinshan-calendar event schedule "Long Workshop" --group 121972817 --startTime "2025-6-19 14:00:00" --days 30 --weekDays 2 --duration 120

# Daily tasks starting from today (no startTime specified, same name for all)
jinshan-calendar event schedule "Daily Task" --group 121972817 --days 30 --weekDays 12345

# Simple meetings (same name for all events, no incrementing)
jinshan-calendar event schedule "Meeting" --group 121972817 --days 30 --weekDays 12345

Remove All Events

# Remove all events from a specific date range
jinshan-calendar event removeAll --group 121972817 --startTime "2025-6-19" --days 30

# Remove all events from today for 7 days
jinshan-calendar event removeAll --group 121972817 --days 7

# Remove all events from a specific date to another date
jinshan-calendar event removeAll --group 121972817 --startTime "2025-6-19" --endTime "2025-8-19"

Week Day Reference

For the schedule command, use these day codes:

| Code | Day | |------|-----| | 1 | Monday | | 2 | Tuesday | | 3 | Wednesday | | 4 | Thursday | | 5 | Friday | | 6 | Saturday | | 7 | Sunday |

Examples:

• 15 = Monday and Friday
• 12345 = Monday to Friday
• 7 = Sunday only
• 1234567 = Every day of the week

Configuration

The CLI stores your authentication cookies in a configuration file located at:

• macOS/Linux: ~/.config/jinshan-calendar/config.json
• Windows: %APPDATA%/jinshan-calendar/config.json

Examples

Workflow Examples

1. Set up for a new project

# 1. Configure authentication
jinshan-calendar auth "your-cookies-here"

# 2. List your groups to find the right group ID
jinshan-calendar groups

# 3. Create a project kickoff meeting
jinshan-calendar event create --group 121972817 "Project Kickoff" --startTime "2025-6-20 10:00:00" --duration 60

2. Schedule recurring meetings

# Create daily standup meetings for the next month
jinshan-calendar event schedule "Daily Standup" --group 121972817 --startTime "2025-6-20 09:00:00" --days 30 --weekDays 12345

# Create weekly team meetings on Wednesdays
jinshan-calendar event schedule "Team Meeting Week $" --group 121972817 --startTime "2025-6-20 14:00:00" --days 90 --weekDays 3

3. Version release schedule

# Create version release events every Monday and Friday
jinshan-calendar event schedule "Release Version 1.$.0" 8 --group 121972817 --startTime "2025-6-20 16:00:00" --days 60 --weekDays 15

4. Clean up old events

# List events to see what needs cleanup
jinshan-calendar event list --group 121972817 --days 7

# Remove specific events
jinshan-calendar event remove 114610227 114610228

# Or bulk remove all events from last month
jinshan-calendar event removeAll --group 121972817 --startTime 2025-5-1 --endTime 2025-5-31

Troubleshooting

Common Issues

1. Authentication Issues

HTTP 403 Error

• Cause: Expired or invalid cookies
• Solution: Update your cookies using jinshan-calendar auth "new-cookie-string"

"No cookies configured" Error

• Cause: Cookies not set up
• Solution: Run jinshan-calendar auth "your-cookie-string"

How to get cookies:

1. Log into Jinshan Calendar
2. Open browser Developer Tools (F12)
3. Go to Network tab
4. Refresh the page
5. Copy the cookie header from any request to rili.wps.cn

2. Date and Time Format Issues

"Invalid date format" Error

• Cause: Wrong date/time format
• Solution:
  • Use YYYY-M-D format for dates (e.g., "2025-6-19")
  • Use YYYY-M-D HH:mm:ss format for times (e.g., "2025-6-19 16:30:00")
  • Examples: "2025-6-19", "2025-6-19 09:00:00"

"Invalid start time format" Error

• Cause: Incorrect time format in schedule command
• Solution: Use proper format: "2025-6-19" for all-day events or "2025-6-19 09:00:00" for timed events

3. Schedule Command Issues

"Event name must contain zero or one $ placeholder" Error

• Cause: Multiple $ placeholders in event name
• Solution: Use zero or one $ placeholder only
  • ✅ "Meeting" (no $)
  • ✅ "Meeting $" (one $)
  • ❌ "Meeting $$" (multiple $)

"Invalid start index" Error

• Cause: Non-numeric or negative start index
• Solution: Use a non-negative number (e.g., 1, 8, 100)

"Invalid week days" Error

• Cause: Invalid day codes
• Solution: Use digits 1-7 only (1=Monday, 2=Tuesday, ..., 7=Sunday)
  • ✅ 12345 (Monday to Friday)
  • ✅ 15 (Monday and Friday)
  • ❌ 18 (invalid day code)

"Invalid duration" Error

• Cause: Non-positive duration value
• Solution: Use a positive number of minutes (e.g., 30, 60, 120)

4. Group and Event Issues

"Invalid group ID" Error

• Cause: Non-numeric or invalid group ID
• Solution:
  1. Run jinshan-calendar groups to list available groups
  2. Use the numeric teamId from the output

"No events found" Message

• Cause: No events in specified time range
• Solution:
  • Check the date range is correct
  • Verify the group ID is correct
  • Try a wider time range

"Failed to create event" Error

• Cause: API error or invalid parameters
• Solution:
  • Check all required parameters are provided
  • Verify group ID is correct
  • Ensure cookies are valid

5. Installation and Command Issues

"Command not found" Error

• Cause: CLI not installed globally or not in PATH
• Solution:

  # Reinstall globally
  npm install -g jinshan-calendar
    
  # Or check if it's in your PATH
  which jinshan-calendar

"Permission denied" Error

• Cause: Insufficient permissions
• Solution:

  # On macOS/Linux, use sudo
  sudo npm install -g jinshan-calendar
    
  # Or fix npm permissions
  npm config set prefix ~/.npm-global

6. Configuration Issues

"Cannot read config file" Error

• Cause: Corrupted or inaccessible config file
• Solution:

  # Remove config and reconfigure
  rm ~/.config/jinshan-calendar/config.json
  jinshan-calendar auth "your-cookies"

Debugging Tips

1. Check Command Syntax

Always use quotes around event names and dates:

# ✅ Correct
jinshan-calendar event create --group 121972817 "Team Meeting" --startTime "2025-6-19 16:30:00"

# ❌ Incorrect
jinshan-calendar event create --group 121972817 Team Meeting --startTime 2025-6-19 16:30:00

2. Verify Group ID

# List all available groups
jinshan-calendar groups

3. Test with Simple Commands

Start with basic commands to verify setup:

# Check version
jinshan-calendar --version

# List events for today
jinshan-calendar event list --days 1

4. Check Date Ranges

When using --startTime and --endTime:

• Ensure end date is after start date
• Use consistent date formats
• Remember that --startTime is now optional (defaults to today)

Getting Help

If you're still experiencing issues:

1. Check the command help:

   jinshan-calendar --help
   jinshan-calendar event schedule --help

2. Verify your setup:

   # Check if cookies are configured
   jinshan-calendar auth
      
   # List available groups
   jinshan-calendar groups

3. Test with minimal parameters:

   # Simple event creation
   jinshan-calendar event create --group YOUR_GROUP_ID "Test Event" --startTime "2025-6-19 10:00:00"

4. Check for updates:

   npm update -g jinshan-calendar

Development

Project Structure

jinshan-calendar/
├── index.mjs          # Main CLI entry point
├── package.json       # Dependencies and metadata
├── README.md          # This file
└── apis/              # API documentation
    └── calendar-api-demos.txt

Dependencies

• commander: Command-line argument parsing
• conf: Configuration management

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the ISC License.

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the help output for each command
3. Open an issue on the project repository

Note: This CLI tool interacts with the Jinshan (WPS) calendar API. Make sure you have proper permissions to access and modify the calendar events you're working with.