# Auth, Environments, and Workspaces

## Authentication

Authenticate before making API calls:

```bash
toggl auth
```

On a machine without a usable browser (SSH, VM, remote CI shell), use the manual flow. The printed login URL redirects to **`accounts.toggl.com/focus/cli/auth-code`** (not localhost) and shows a copyable authorization code:

```bash
toggl auth --manual
```

Non-interactive environments can pass the code directly (must be from the same shell session’s printed login link—PKCE requires matching verifier). Use **`--manual`** so token exchange uses the accounts callback redirect:

```bash
toggl auth --manual --code 'YOUR_CODE'
toggl auth --code 'https://accounts.toggl.com/focus/cli/auth-code?code=YOUR_CODE'
```

The default `toggl auth` flow still uses `http://localhost:8716/callback` on the same machine and shows a branded success page in the browser tab.

The same flags work for `npx @togglhq/mcp auth` when running the MCP package entrypoint outside the MCP host.

If the account has multiple workspaces, pass the workspace explicitly:

```bash
toggl auth --workspace-id <workspace-id>
```

When `--profile` is omitted, the CLI saves the account under an account-based profile name such as `user-12345` and makes it active. Use an explicit profile name only when the user asks for a specific name:

```bash
toggl auth --profile <name>
toggl --profile <name> --json tasks list --project-id <project-id>
```

Credentials are stored in `~/.toggl/focus-tools.json`. Sessions refresh automatically; re-run `toggl auth` to switch workspaces or after long inactivity.

## Profiles

List saved profiles:

```bash
toggl --json profile list
```

Show the active profile:

```bash
toggl --json profile current
```

Switch the default account and environment:

```bash
toggl --json profile switch <profile>
```

Remove a saved profile. With `--json` or when stdin/stdout is not a TTY, pass the profile name; in an interactive terminal you can omit it to pick from the list.

```bash
toggl --json profile remove <profile>
```

## Workspaces

List cached workspaces:

```bash
toggl --json workspace list
```

Refresh workspace metadata from the account:

```bash
toggl --json workspace list --refresh
```

Switch the active workspace for the current profile. With `--json` or when not a TTY, pass the workspace id; in an interactive terminal you can omit it to pick from cached workspaces (refresh with `toggl workspace list --refresh` if needed).

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

Override workspace for one call without changing the active profile:

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

When a command returns unexpected missing data, verify the active profile, environment, and workspace before assuming the resource does not exist.

## Workspace settings

`workspace-settings update` expects `--data` with a top-level `payload` object whose **only** mutable workspace fields live under **`payload.settings`** (not alongside `payload` at the root). Discover keys and value shapes from `workspace-settings list` on the same workspace before patching.

```bash
toggl workspace-settings update --dry-run --data '{"payload":{"settings":{}}}'
```

## Skill and CLI Maintenance

Install or refresh the agent skill (delegates to the `skills` CLI installed with `@toggl/cli`):

```bash
toggl skill setup
```

After upgrading the CLI, run the same flow again so agents pick up skill changes:

```bash
toggl skill sync
```

Non-interactive setup can pass target agents and confirmations to the `skills` installer:

```bash
toggl skill setup --agent cursor --global --copy --yes
toggl skill setup --agent cursor codex --copy --yes
```

Prefer the default symlink install over `--copy` so skill content stays aligned when you upgrade `@toggl/cli` without re-running setup.

Update a globally installed CLI:

```bash
toggl update
```

Preview the update command without running it:

```bash
toggl update --dry-run
toggl --json update --dry-run
```

`toggl update` updates the CLI package only. Run `toggl skill setup` again to refresh the installed agent skill after updating.