TimeMachine CLI Tool

Version: 1.3.0

A CLI tool for interacting with the TimeMachine Timesheet System. This tool is useful for:

• Generating bulk time entries (e.g., for data migration or testing)
• Listing users and their IDs
• Listing projects and their IDs

Installation

1. Clone this repository or copy the script files to your local machine.
2. Navigate to the script directory (cd scripts/timeentrygenerator).
3. Install dependencies:

npm install

4. Make the main script executable (optional, depending on usage):

chmod +x time-entry-generator.ts

5. Link the package for global use (optional, allows running time-entry-generator directly):

npm link

(If you link, you might call it as time-entry-generator <command> instead of npx ts-node time-entry-generator.ts <command>)

Configuration

Create a .env file in the script's directory (scripts/timeentrygenerator) with your API key:

TIMEMACHINE_API_KEY=your_api_key_here

Global Options

These options can be used with any command:

| Option | Short | Description | Default | |-------------|-------|-------------------------------|------------------------------------------| | --base-url| -b | API base URL | https://www.codeclock.xyz/api | | --verbose | -v | Show detailed output | false | | --help | -h | Display help for command | |

Commands

The script now uses a command-based structure. You must specify a command after the script name.

generate

Generates time entries based on specified criteria. The initial configuration summary will display user and project names (if fetched) and day names for clarity in both live and dry runs.

Usage:

npx ts-node time-entry-generator.ts generate [options]

Options for generate:

| Option | Short | Description | Default | |----------------|-------|-------------------------------------------------|--------------------------------| | --user-id | -u | User ID (required) | - | | --project-id | -p | Project ID (required) | - | | --start-date | -s | Start date (YYYY-MM-DD) | 30 days ago | | --end-date | -e | End date (YYYY-MM-DD) | Today | | --days | -d | Days to log time (1=Monday, 7=Sunday) | 1,2,3,4,5 (weekdays) | | --hours | -H | Hours per day (Note: short option changed to -H) | 8 | | --dry-run | | Perform a dry run. The summary will show user/project names and day names. The per-entry preview will also use these descriptive names. No actual API calls to create entries are made. | false |

Examples for generate:

Generate 8-hour entries for user 1, project 1, for weekdays over the last 30 days:

npx ts-node time-entry-generator.ts generate -u 1 -p 1

Create 4-hour entries for user 1, project 2, for Mondays and Wednesdays only:

npx ts-node time-entry-generator.ts generate -u 1 -p 2 -d 1,3 -H 4

Create entries for a specific date range with verbose logging:

npx ts-node time-entry-generator.ts generate -u 1 -p 2 -s 2025-01-01 -e 2025-01-31 -v

Test without making actual API calls (dry run):

npx ts-node time-entry-generator.ts generate -u 1 -p 2 --dry-run

list-users

Lists all users and their details from the TimeMachine API.

Usage:

npx ts-node time-entry-generator.ts list-users [global options]

Example:

npx ts-node time-entry-generator.ts list-users

To use a different base URL:

npx ts-node time-entry-generator.ts list-users --base-url https://custom.api.com

list-projects

Lists all projects and their details from the TimeMachine API.

Usage:

npx ts-node time-entry-generator.ts list-projects [global options]

Example:

npx ts-node time-entry-generator.ts list-projects

Integration with TimeMachine API

The tool interacts with the TimeMachine API using the API key from your .env file.

• generate uses the /api/time-entries endpoint.
• list-users uses the /api/users endpoint.
• list-projects uses the /api/projects endpoint.

Troubleshooting

If you encounter issues:

1. Ensure your TIMEMACHINE_API_KEY in .env is correct and the file is in the scripts/timeentrygenerator directory.
2. Check that the --base-url (or its default) is pointing to the correct API endpoint.
3. For generate, verify that the user and project IDs exist in the system (you can use list-users and list-projects to check!).
4. Use the global --verbose or -v flag with any command to see detailed error messages or API responses.
5. For generate, try --dry-run first to verify your configuration before making live changes.

Dependencies

• axios: For making HTTP requests
• commander: For parsing command-line arguments
• dotenv: For loading environment variables
• luxon: For date handling
• ora: For displaying progress spinner
• chalk: For colored console output