Skip to main content

​
Authentication and Profiles

​
Ask for an Authenticated Workflow

Name the profile and the outcome you need:

​
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:
Named personas inside that same workspace are also lazy:

​
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:
--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:
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.