# Credentials

Source: https://zshot-cli.com/reference/navigator/credentials/
Markdown: https://zshot-cli.com/reference/navigator/credentials/index.md
Section: [Reference](https://zshot-cli.com/reference/) › [Navigator](https://zshot-cli.com/reference/navigator/)

A credential is a named value ZShot types for the navigator. The navigator sees the name; the value never enters the model's context.

Wherever page text shows a typed value, as a text field or a greeting does, the navigator reads `credential:NAME` in its place. A screenshot shows the page as it is, so a navigator shown one after VISION sees any credential the page displays.

| Source | Flag | Read |
| --- | --- | --- |
| A value | [`--navigator-credential`](/reference/flags/navigator/navigator-credential) | From the command line or the request |
| An environment variable | [`--navigator-credential-env`](/reference/flags/navigator/navigator-credential-env) | Once, at startup |
| A helper | [`--navigator-credential-helper`](/reference/flags/navigator/navigator-credential-helper) | Each time ZShot types it |

A credential is typed exactly as given, trailing spaces included, and must not be empty. Omit a credential to leave its field blank.

An environment variable is read before the environment is cleared for Chromium, so no helper process inherits it.

## Scope

A credential is offered only on pages within the start URL's registrable domain. [`--navigator-credential-origin`](/reference/flags/navigator/navigator-credential-origin) replaces that scope, as for a login that hands off to another domain. A credential selected by several entries may be typed wherever any of them allows.

## Server

A server takes `navigator_credential` from each request, and refuses `--navigator-credential` at startup. Its own credentials come from `--navigator-credential-env` or `--navigator-credential-helper`, are offered to every request, and a request cannot reuse their names.

A request's `navigator_credential_origin` maps a name or name pattern to a list of globs, and scopes only the request's own `navigator_credential` entries. Credentials configured at startup keep their startup origins.

## Helpers

A helper's `SPEC` is a command line or an `https://` URL; `http://` is accepted for loopback hosts. In real use the helper reads a secret store, as `op read op://Vault/Site/password` or `security find-generic-password -w -s zshot-cli.com` do.

[`--navigator-credential-secret`](/reference/flags/navigator/navigator-credential-secret) sends every helper a shared secret, so a helper can confirm the request came from a ZShot you configured. Its `ZSHOT_NAVIGATOR_CREDENTIAL_SECRET` form is read at startup and removed from ZShot's environment before the browser starts.

### Executable Helpers

A command line is split with shell quoting rules and run without a shell. The program is a path, or a bare name found on `PATH` at startup. It receives the environment ZShot passes to Chromium's own helpers: time zone, locale, `HOME`, `PATH`, `TMPDIR`, proxy and certificate variables, `LC_*` and `XDG_*`, minus `LD_LIBRARY_PATH` and `DYLD_*`. It also receives the names given with [`--navigator-credential-helper-env`](/reference/flags/navigator/navigator-credential-helper-env), and:

| Variable | Value |
| --- | --- |
| `ZSHOT_CREDENTIAL_NAME` | The credential name |
| `ZSHOT_CREDENTIAL_URL` | The page URL where the value is typed |
| `ZSHOT_CREDENTIAL_REQUEST` | The request document below, as JSON |

A `--navigator-credential-secret` arrives as one line on stdin; without one, stdin is `/dev/null`. The secret never enters a helper's environment or the request document.

The helper prints the value on stdout as one line of at most 64 KiB; a trailing newline is dropped. A non-zero exit, empty output, or a value with a line break fails the fill. stderr is kept for the error message, so a helper must not print secrets there.

At startup ZShot checks that each program exists, is a regular file this user can execute, and is not setuid, then records its identity. A failed check exits with code 5. A program that changes on disk afterwards is not run.

### HTTP Helpers

An HTTP helper receives a `POST` with `Content-Type: application/json`, and a `--navigator-credential-secret` as `Authorization: Bearer <secret>`:

```json
{"credential": {"name": "password", "url": "https://zshot-cli.com/example_assets/zrm/"}}
```

and answers `200` with:

```json
{"credential": {"value": "hunter2"}}
```

Any other status, a redirect, a body over 64 KiB, or a body without `credential.value` fails the fill. Redirects are not followed and no proxy is used.

### Failures

A call is bounded by [`--navigator-credential-helper-timeout`](/reference/flags/navigator/navigator-credential-helper-timeout) and never retried. An executable past the limit is killed with its process group. A failure during navigation exits with code 14 and `Credential helper 'NAME' failed: <reason>`; under [`--server`](/reference/flags/server/server) the response is `502` with the failure class.

ZShot logs each call at `debug` before it starts, each answer at `info` with the helper and its duration, and each failure at `error` with the reason. The value never appears in a log.

## Related

Flags:

- [`--navigator-credential`](https://zshot-cli.com/reference/flags/navigator/navigator-credential/)
- [`--navigator-credential-env`](https://zshot-cli.com/reference/flags/navigator/navigator-credential-env/)
- [`--navigator-credential-helper`](https://zshot-cli.com/reference/flags/navigator/navigator-credential-helper/)
- [`--navigator-credential-helper-env`](https://zshot-cli.com/reference/flags/navigator/navigator-credential-helper-env/)
- [`--navigator-credential-helper-timeout`](https://zshot-cli.com/reference/flags/navigator/navigator-credential-helper-timeout/)
- [`--navigator-credential-secret`](https://zshot-cli.com/reference/flags/navigator/navigator-credential-secret/)
- [`--navigator-credential-origin`](https://zshot-cli.com/reference/flags/navigator/navigator-credential-origin/)

Topics:

- [Log in, then capture](https://zshot-cli.com/examples/navigate-login/)
- [Exit Codes](https://zshot-cli.com/reference/exit_codes/)
- [op read](https://developer.1password.com/docs/cli/reference/commands/read/) — 1Password CLI

## Navigation

- [Examples](https://zshot-cli.com/examples/)
- [Download](https://zshot-cli.com/download/)
- [Purchase](https://zshot-cli.com/purchase/)
- [Reference](https://zshot-cli.com/reference/)
  - [Formats](https://zshot-cli.com/reference/formats/)
  - [Flags](https://zshot-cli.com/reference/flags/)
  - [Agents](https://zshot-cli.com/reference/agents/)
  - [Configuration](https://zshot-cli.com/reference/configuration/)
  - [Crawling](https://zshot-cli.com/reference/crawling/)
  - [Docker](https://zshot-cli.com/reference/docker/)
  - [Exit Codes](https://zshot-cli.com/reference/exit_codes/)
  - [Linux](https://zshot-cli.com/reference/linux/)
  - [LLM Connections](https://zshot-cli.com/reference/llm_connections/)
  - [LLM Formatting](https://zshot-cli.com/reference/llm_formatting/)
  - [Local Inputs](https://zshot-cli.com/reference/inputs/)
  - [Navigator](https://zshot-cli.com/reference/navigator/)
    - [Actions](https://zshot-cli.com/reference/navigator/actions/)
    - [Navigators](https://zshot-cli.com/reference/navigator/navigators/)
    - [Scope](https://zshot-cli.com/reference/navigator/scope/)
    - **Credentials**
    - [Data and Files](https://zshot-cli.com/reference/navigator/data-and-files/)
  - [Security](https://zshot-cli.com/reference/security/)
  - [Server](https://zshot-cli.com/reference/server/)
  - [Shell completions](https://zshot-cli.com/reference/shell_completions/)
  - [Storage](https://zshot-cli.com/reference/storage/)
  - [Timeouts](https://zshot-cli.com/reference/timeouts/)
  - [Web Bot Auth](https://zshot-cli.com/reference/web_bot_auth/)
- [Support](https://zshot-cli.com/support/)
- [Changelog](https://zshot-cli.com/changelog/)

Site index: https://zshot-cli.com/llms.txt