> ## Documentation Index
> Fetch the complete documentation index at: https://webcmd.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and Profiles

> Ask agents to use logged-in websites without putting credentials in adapters or prompts.

# Authentication and Profiles

## Ask for an Authenticated Workflow

Name the profile and the outcome you need:

```text theme={null}
Use Webcmd with my `work` profile to complete this task on Acme Billing. If the profile is not authenticated, pause and give me the sign-in link or browser handoff. Never store credentials in the adapter.
```

## Named Profiles

Profiles are cookie jars and authentication scope. Sessions are browser
windows/workspaces within a profile; separate Sessions let multiple agents use
the same profile in parallel. Use a named profile when work and personal
accounts, customers, or environments must stay separate.

## Hosted Profiles

Webcmd Cloud scopes every hosted profile to a workspace. A workspace is an ambient container the CLI resolves once per invocation: the `--workspace <id>` flag if present, otherwise the `WEBCMD_WORKSPACE` environment variable, otherwise an implicit default workspace. Within that workspace, `--profile <name>` selects a persona; an unset or default profile lazily creates that workspace's own `default` profile the first time it is used.

### B2C

A single end user runs hosted commands with no setup. The implicit default workspace and its `default` profile are created lazily on first use:

```bash theme={null}
webcmd github whoami
```

Named personas inside that same workspace are also lazy:

```bash theme={null}
webcmd --profile work github whoami
```

### B2B2C

An enterprise backend puts each downstream user in their own workspace by setting `WEBCMD_WORKSPACE` per invocation. Each workspace gets its own lazily created profiles, including its own `default`, isolated from every other workspace:

```bash theme={null}
WEBCMD_WORKSPACE=user_64256 webcmd github whoami
WEBCMD_WORKSPACE=user_64256 webcmd --profile work github whoami
```

`--profile <name>` still selects a persona within the ambient workspace; it never crosses workspace boundaries.

Hosted `profile list` returns profile rows; `delete` returns `{ "ok": true, "deleted": true }`. Public profile fields are `id`, `name`, `workspace`, `default`, `status`, `createdAt`, `updatedAt`, and `lastUsedAt`. `status` is `pending` while the hosted profile is being provisioned and `available` once it is ready. Cloud provider identifiers are never exposed as Webcmd API fields.

Delete hosted profiles only by immutable ID:

```bash theme={null}
webcmd profile delete profile_abc123
```

Deletion permanently removes that hosted browser state and its saved sign-in state.

## When You Need to Sign In

When a profile needs interactive sign-in, complete it directly in the browser;
never share credentials through chat. The handoff belongs to the Session that
started it. After signing in, run the returned verification command verbatim;
it includes the Session selector when applicable. Webcmd blocks `session close`
while that Session has a live handoff.

## Credential Safety

Credentials never belong in prompts or adapter code. Ask the agent to use an authenticated profile and pause for a sign-in handoff instead of sharing passwords, cookies, or API keys.

## Local and Hosted Authentication

In local mode, `webcmd <site> login` opens the foreground Webcmd browser and returns `action_required` immediately. Complete sign-in in that browser, tell the agent when you are done, and let it run the returned verification command before retrying the original task. Never send credentials, OTPs, cookies, or recovery codes through chat.

Hosted mode returns a Webcmd-owned live authentication view when interactive sign-in is required. Complete the sign-in there before the agent continues.