# Common Workflows

## Find IDs Before Acting

Resolve project IDs:

```bash
toggl --json projects list
```

Resolve task IDs:

```bash
toggl --json tasks list --project-id <project-id>
```

Resolve status IDs:

```bash
toggl --json statuses list
```

Resolve user IDs:

```bash
toggl --json users list
```

If multiple resources match a user-provided name, ask before mutating.

## Create a Task in a Project

1. Resolve the project ID.
2. Create the task.
3. Return the created task JSON or summarize the created ID.

```bash
toggl --json projects list
toggl --json tasks create --data '{"name":"Write release notes","project_id":123456}'
```

## Move a Task to a Status

1. Resolve the task ID.
2. Resolve the status ID.
3. Dry-run if either ID was inferred.
4. Update the task.

```bash
toggl --json tasks list --project-id <project-id>
toggl --json statuses list
toggl tasks update --task-id <task-id> --payload-status-id <status-id> --dry-run
toggl --json tasks update --task-id <task-id> --payload-status-id <status-id>
```

## Start Tracking Work

1. Resolve the task ID when the user names a task.
2. Start the activity timer.

```bash
toggl --json tasks list --project-id <project-id>
toggl --json time-entries start --task-id <task-id>
```

Start a break:

```bash
toggl --json time-entries start --type break
```

Stop the running timer:

```bash
toggl --json time-entries stop
```

## Plan a Time Block

1. Resolve the task ID.
2. Convert user-provided times to RFC 3339 datetimes.
3. Dry-run when the time range was inferred.
4. Create the block.

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

## Switch Workspace

List workspaces, refresh if needed, then switch:

```bash
toggl --json workspace list
toggl --json workspace list --refresh
toggl --json workspace switch <workspace-id>
```

For one command only:

```bash
toggl --workspace-id <workspace-id> --json tasks list --project-id <project-id>
```