claude_profile 1.2.0

# Verb :: use

Atomically switches the active Claude Code session to a named account. Writes the named account's credentials to `~/.claude/.credentials.json` via write-then-rename and updates the per-machine active marker. Optionally refreshes an expired token or spawns a keep-alive subprocess after switching.

### Nouns

| # | Noun | Command | Idempotent | Requires Session |
|---|------|---------|-----------|-----------------|
| 1 | [account](../command_noun/001_account.md) | `.account.use` | Conditional | No |

### Behavioral Contract

**Pre-conditions:**
- Named account exists in credential store (`{name}.credentials.json` readable)
- `$HOME` environment variable set

**Post-conditions:**
- `~/.claude/.credentials.json` updated to named account's credentials (atomic write-then-rename)
- Per-machine active marker updated to reflect new active account
- If `touch::1` and target account is idle, subprocess spawned to activate session

**Side effects:**
- Overwrites `~/.claude/.credentials.json` (atomic — no partial writes)
- If `refresh::1` and token is expired, isolated subprocess attempts token refresh before switch
- If `touch::1`, post-switch subprocess spawned using `imodel::` model and `effort::` setting
- If `set_model::` provided, writes model preference to session configuration

### Idempotency

**Conditional.** Re-activating the already-active account is a no-op (idempotent). Switching to a different account modifies `~/.claude/.credentials.json` and the active marker (not idempotent across calls with different `name::` values).

### Common Parameters

| Parameter | Semantics | Required |
|-----------|-----------|----------|
| `name::` | Account to activate (email or unambiguous prefix) | Yes |
| `touch::` | Spawn keep-alive subprocess after switch if account is idle | No |
| `refresh::` | Attempt token refresh if expired before switching | No |
| `imodel::` | Model for post-switch subprocess (`auto`/`sonnet`/`opus`/`haiku`/`keep`) | No |
| `effort::` | Effort level for post-switch subprocess | No |
| `set_model::` | Write model preference to session config after switch | No |
| `force::` | Bypass G5 ownership gate; allow switching to non-owned account | No |
| `dry::` | Validate without switching | No |
| `trace::` | Emit diagnostic trace output | No |

### State Transition Pattern

**Transitions state.** Changes which account is active via atomic write-then-rename to `~/.claude/.credentials.json`; updates the per-machine active marker.

```
[saved]  --account.use name::EMAIL--> [active]
[active] --account.use name::other--> [saved]   (prior active → saved; target → active)
```

### Cross-References

| File | Relationship |
|------|-------------|
| [feature/004_account_use.md](../../feature/004_account_use.md) | Atomic switch algorithm and active marker update |
| [feature/025_per_machine_active_marker.md](../../feature/025_per_machine_active_marker.md) | `_active_{machine}_{user}` marker semantics |
| [feature/026_subprocess_model_effort.md](../../feature/026_subprocess_model_effort.md) | Model and effort selection for post-switch subprocess |
| [feature/017_token_refresh.md](../../feature/017_token_refresh.md) | Token refresh via isolated subprocess |
| [feature/036_account_ownership.md](../../feature/036_account_ownership.md) | G5 ownership gate — exits 1 when account owned by different identity; `force::1` bypasses G5 |

### Referenced Commands

| # | Command | Role |
|---|---------|------|
| 1 | [`.account.use`](../command/001_account.md#command--5-accountuse) | Switch active session to named account |