# Time Blocks

Use time block commands to inspect, create, update, and delete scheduled time blocks.

## Commands

List time blocks for a date range:

```bash
toggl --json time-blocks list --date-from 2026-04-01 --date-to 2026-04-07
```

Get one time block:

```bash
toggl --json time-blocks get --task-id <task-id> --time-block-id <time-block-id>
```

Create a time block:

```bash
toggl --json time-blocks create --data '{"task_id":12345,"payload":{"start":"2026-04-06T09:00:00Z","end":"2026-04-06T11:00:00Z"}}'
```

Update a time block:

```bash
toggl --json time-blocks update --data '{"task_id":12345,"time_block_id":67890,"payload":{"start":"2026-04-06T10:00:00Z","end":"2026-04-06T12:00:00Z"}}'
```

Delete a time block only after explicit user confirmation:

```bash
toggl --json time-blocks delete --task-id <task-id> --time-block-id <time-block-id> --yes
```

## Agent Workflow

Use RFC 3339 timestamps for exact scheduled blocks. If the user gives local times, preserve the intended time zone offset when possible.

Time block commands usually need both `task_id` and `time_block_id`. Resolve both IDs with a list or get command before mutating.

Use `--dry-run` before creating or updating blocks when times were inferred from natural language.