Kimai Time Tracking

Do NOT activate for:

• General time questions ("What time is it?")
• Other time-tracking tools (Toggl, Clockify, etc.)
• Calendar/scheduling without Kimai context

Environment Setup

Required Environment Variables:

• KIMAI_BASE_URL - Full URL to Kimai instance (e.g., https://kimai.example.com)
• KIMAI_API_TOKEN - Bearer token for authentication

Optional:

• KIMAI_WORKSPACE - Path for exports/temp files (defaults to ~/.openclaw/workspace/kimai)

API Permissions required depend on operation:

• view_own_timesheet, create_own_timesheet, edit_own_timesheet, delete_own_timesheet
• view_other_timesheet (for viewing other users' entries)
• view_customer, edit_customer, delete_customer
• view_project, edit_project, delete_project
• view_activity, edit_activity, delete_activity
• view_team, edit_team, create_team, delete_team
• view_invoice (for invoice operations)
• view_user (for user management)

Compatibility: Requires Kimai 2.x with REST API enabled. Internet access required. Linux/macOS supported.

Workflow

1. Quick Time Tracking

# List recent activities (to find project/activity IDs)
./scripts/kimai_cli.py timesheets recent

# Start tracking
./scripts/kimai_cli.py timesheets start --project 1 --activity 5 --description "Implementing API"

# Check active timers
./scripts/kimai_cli.py timesheets active

# Stop tracking
./scripts/kimai_cli.py timesheets stop --id 123

2. Data Management Workflow

# Create customer → Project → Activity hierarchy
./scripts/kimai_cli.py customers create --name "Acme Corp" --country DE --currency EUR --timezone Europe/Berlin
./scripts/kimai_cli.py projects create --name "Website Redesign" --customer 1
./scripts/kimai_cli.py activities create --name "Development" --project 1

# List with filters
./scripts/kimai_cli.py timesheets list --customer 1 --begin "2024-01-01T00:00:00" --exported 0

3. Export/Invoice Workflow

# Mark timesheets as exported (locks them)
./scripts/kimai_cli.py timesheets export --id 123

# List invoices
./scripts/kimai_cli.py invoices list --status pending --begin 2024-01-01T00:00:00

CLI Tool Reference

Use scripts/kimai_cli.py for all operations. Structure follows API endpoints:

Timesheets (timesheets)

• list - List entries (supports pagination, filters: user, customer, project, activity, tags, date range, exported status)
• get <id> - Fetch single entry
• create - Create manual entry or start timer (omit --end for active tracking)
• update <id> - Patch existing entry
• delete <id> - Requires confirmation (destructive)
• stop <id> - Stop active timer
• restart <id> - Restart finished entry (creates new)
• duplicate <id> - Copy entry (resets export status)
• active - List currently running timers
• recent - Recent unique working sets (last activity per project/activity combination)
• export <id> - Toggle export/lock status

Customers (customers)

• list - List customers (filter: visible, term)
• get <id> - Fetch customer details
• create - Create new customer
• update <id> - Update customer
• delete <id> - Requires confirmation (cascades to projects/activities/timesheets)
• meta <id> - Update custom fields
• rates <id> - Manage customer-specific rates

Projects (projects)

• list - List projects (filter: customer, visible, date range)
• get <id> - Fetch project
• create - Create project (requires customer ID)
• update <id> - Update project
• delete <id> - Requires confirmation (cascades to activities/timesheets)
• rates <id> - Manage project rates

Activities (activities)

• list - List activities (filter: project, visible, global only)
• get <id> - Fetch activity
• create - Create activity (can be global or project-specific)
• update <id> - Update activity
• delete <id> - Requires confirmation (cascades to timesheets)
• rates <id> - Manage activity rates

Teams (teams)

• list, get, create, update, delete
• member-add <team-id> <user-id> - Add team member
• member-remove <team-id> <user-id> - Remove member
• grant-customer <team-id> <customer-id> - Grant customer access
• grant-project <team-id> <project-id> - Grant project access
• grant-activity <team-id> <activity-id> - Grant activity access

Users (users)

• list - List users (requires view_user permission)
• me - Current user info
• get <id> - User details
• create - Create user (admin)
• update <id> - Update user

Invoices (invoices)

• list - List invoices (filter: date range, customer, status)
• get <id> - Invoice details

System (system)

• ping - Test connectivity
• version - Kimai version info
• plugins - Installed plugins
• config - Timesheet configuration
• colors - Color codes

Safety & Boundaries

⚠️ DESTRUCTIVE OPERATIONS

• delete operations on customers, projects, activities, timesheets, teams, or tags require explicit user confirmation.
• Deleting customers cascades to all linked projects, activities, and timesheets [1].
• Deleting projects cascades to activities and timesheets [1].
• The CLI will show a preview of affected data and require "yes" confirmation.

API Security:

• API token is passed via Authorization: Bearer header [1].
• Token is never logged or stored in CLI output.
• Use --dry-run flag for testing (simulates API calls without executing).

Rate Limiting & Pagination:

• API returns paginated results (default 50 items) [1].
• CLI auto-handles pagination for list commands (fetches all pages or respects --limit).
• Use --page and --size for manual pagination control.

Data Privacy:

• Timesheet data may contain sensitive information.
• Export files are saved to workspace with restricted permissions (600).
• Redact personal data (emails, names) when sharing debug output.

Workspace Safety:

• All file exports (CSV, JSON) default to KIMAI_WORKSPACE or ~/.openclaw/workspace/kimai.
• Never write to system directories outside workspace without explicit confirmation.

Input/Output Specifications

Inputs:

• Entity IDs (integers)
• ISO 8601 datetime strings (YYYY-MM-DDTHH:mm:ss)
• JSON data for create/update operations (via --json file or CLI args)
• Filter parameters (customer, project, activity IDs, date ranges, visibility)

Outputs:

• JSON (default, pipe-friendly)
• Table format (--format table for human readability)
• CSV (--format csv for exports)
• Exit codes: 0 (success), 1 (API error), 2 (validation error), 3 (cancelled by user)

Success Criteria:

• HTTP 200/201 for successful operations
• Valid JSON response structure matching API schemas [1]
• For exports: File created in workspace with expected record count

Examples

Start tracking with description

./scripts/kimai_cli.py timesheets create \
  --project 5 \
  --activity 12 \
  --description "Client meeting - requirements analysis" \
  --tags "meeting,urgent"

List and export non-exported hours

# Find billable hours not yet exported
./scripts/kimai_cli.py timesheets list \
  --exported 0 \
  --billable 1 \
  --begin "2024-01-01T00:00:00" \
  --end "2024-01-31T23:59:59" \
  --format csv > january_hours.csv

Update custom fields (meta)

./scripts/kimai_cli.py customers meta 42 \
  --name "order_number" \
  --value "PO-2024-001"

Create team and assign resources

./scripts/kimai_cli.py teams create --name "Development Team" --members '[{"user": 1, "teamlead": true}]'
./scripts/kimai_cli.py teams grant-project 1 5

Error Handling

Common HTTP codes:

• 200 - Success
• 201 - Created
• 204 - No content (successful delete)
• 400 - Bad request (validation error, missing fields)
• 401 - Unauthorized (invalid/expired token)
• 403 - Forbidden (insufficient permissions)
• 404 - Not found (invalid ID)
• 409 - Conflict (overlapping timesheet if not allowed by config)

CLI behavior:

• Validates required fields before API call (e.g., project+activity for timesheets [1])
• Pretty-prints validation errors from API
• Suggests fixes (e.g., "Did you mean to use 'PATCH' instead of DELETE? Try setting visible=false to hide instead of delete")

Validation

Validate this skill using the Openclaw skills validator:

skills-ref validate ./kimai-time-tracking

Test API connectivity:

export KIMAI_BASE_URL="https://your-kimai.example.com"
export KIMAI_API_TOKEN="your-api-token"
./kimai-time-tracking/scripts/kimai_cli.py system ping

References

• Kimai REST API Docs: https://www.kimai.org/documentation/rest-api.html
• Pagination Guide: https://www.kimai.org/documentation/api-pagination.html
• API Spec: references/api-reference.json (complete OpenAPI schema)