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

# Authentication and workspaces

> Sign in, check your session, choose workspaces, and sign out safely.

Use this page when you need to sign in from the terminal, confirm which account is active, or fix workspace access.

## What this is

The CLI uses browser-based authentication.

After sign-in, it stores a rotating local session in your operating system credential store when available.

The current stores are:

* macOS: macOS Keychain
* Linux: Linux Secret Service when available
* fallback: a private local file with `0600` permissions

If an OS credential service is unavailable, the CLI uses the private file fallback and prints a note.

## Sign in

Run:

```bash theme={null}
custory login
```

The CLI opens your browser and prints the authorization URL and code.

If you are already signed in, it reports the current account instead of starting a new login.

## Sign in without opening a browser

Use `--no-browser` when the terminal cannot open a browser automatically:

```bash theme={null}
custory login --no-browser
```

Copy the printed `Visit` URL into a browser and complete the sign-in flow.

## Force a new login

Use `--force` when the wrong account is active:

```bash theme={null}
custory login --force
```

This starts a new browser sign-in even when the CLI has a valid local session.

## Check status

Run:

```bash theme={null}
custory status
```

This shows:

* the signed-in user
* the number of accessible workspaces
* where the local session is stored
* the latest setup status when one exists

For scripts:

```bash theme={null}
custory status --json
```

## List workspaces

Run:

```bash theme={null}
custory workspace list
```

The human-readable output shows workspace name, slug, and role.

Use a workspace slug or ID when a name is ambiguous:

```bash theme={null}
custory init --workspace acme --website https://acme.com --journey recommended --yes
```

## Workspace permissions

The CLI can only use workspaces your Custory account can access.

For journey creation and write actions, use a workspace where you have write permission. Viewer access can be enough for read-only operations, but it is not enough for creating or updating journey structure.

If a workspace is missing, confirm that you are signed in with the right account or ask a workspace owner to invite you.

## Sign out

Run:

```bash theme={null}
custory logout
```

This removes the local credential and revokes the remote CLI session when possible.

For scripts:

```bash theme={null}
custory logout --json
```

## Session recovery

If a command says the session expired, run:

```bash theme={null}
custory doctor --refresh
```

or sign in again:

```bash theme={null}
custory login
```

If browser authorization expires before you finish, rerun `custory login`.

## Security note

Never paste real credentials, device codes, account IDs, or session identifiers into shared docs, issues, or chat messages.

When asking for help, share the command you ran, the error code, and safe `custory doctor` output. Do not share tokens.

## Next step

Read [CLI quickstart](/cli/quickstart) to create your first journey, or [Troubleshooting](/cli/troubleshooting) if sign-in is not working.