@latentsearch/timemachine-cli/README.md

CLI tool for TimeMachine API. Generates time entries, lists users/projects, and features an enhanced dry-run output for generation.

# 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:

```bash
npm install
```

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

```bash
chmod +x time-entry-generator.ts
```

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

```bash
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:**

```bash
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:
```bash
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:
```bash
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:
```bash
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):
```bash
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:**

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

**Example:**

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

To use a different base URL:
```bash
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:**

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

**Example:**

```bash
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