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

# blobhub workflow listener

> Enable or disable a declared listener for one session

`listener enable` and `listener disable` switch a declared [listener](https://docs.blobhub.io/blob-types/workflow/workflows/listeners.md) on or
off for one session. The definition and every other session are untouched.

## Synopsis

```bash theme={null}
blobhub workflow listener <enable|disable> <session> <listener> [--file <manifest>]
```

| Flag | Default | Description |
| - | - | - |
| `enable` or `disable` | required | The state to set for this session. |
| `<session>` | required | A session reference, as for [`events`](https://docs.blobhub.io/cli/workflow/commands/events#the-session-argument). |
| `<listener>` | required | A declared listener's alias or id. |
| `--file`, `-f` | none | Manifest naming a bare session's blob. Refused beside a qualified session. |

## What it does

1. Resolves the blob and revision, then the session. The session may have any status.
2. Sends `set_session_listener` with the listener and the new state.
3. Prints the listener's effective state and whether the session overrides its definition:

```text theme={null}
orchestrate: off (session) (overridden by the session)
```

The switch is an override, not a rewrite. Setting a value equal to the definition's own clears the override, and the
line then reads `(as the definition says)`. It raises no event. A batch that comes due while the listener is off in the
session is dropped with no outcome, as described under
[The switch](https://docs.blobhub.io/blob-types/workflow/workflows/listeners.md#the-switch).

Under `--json` the payload is `{session_id, listener}`, the listener entry as the platform returns it, alongside the
envelope's `schema_version`.

The write is retried only when it provably never ran, as every write in this CLI is. Rerunning the command is safe: it
sets the same state again.

## Errors

| Code | When |
| - | - |
| `SESSION_REFERENCE_INVALID` | `<session>` is malformed, bare without `-f`, or qualified beside `-f`. |
| `SESSION_NOT_ACCESSIBLE` | The session is absent, or this key cannot read it. |
| `LISTENER_NOT_FOUND` | `<listener>` is not a declared listener of the revision. |
| `MANIFEST_NOT_FOUND`, `MANIFEST_INVALID`, `MANIFEST_TYPE_MISMATCH`, `MANIFEST_VERSION_UNSUPPORTED` | The manifest given with a bare session is absent or unusable. |
| `BLOB_NOT_ACCESSIBLE`, `BLOB_NOT_WORKFLOW`, `REVISION_NOT_ACCESSIBLE`, `REVISION_NOT_WRITABLE` | The blob or revision cannot be resolved, or its status is not `ready`. |
| `CREDENTIALS_NOT_FOUND`, `PROFILE_NOT_FOUND`, `INSECURE_CREDENTIALS_PERMISSIONS` | No usable credential, or a credentials file the CLI refuses to read. |
| `API_RATE_LIMITED`, `API_TRANSIENT_ERROR`, `API_NETWORK_ERROR` | The write failed. A 5xx or a dropped connection may have reached the platform; the switch is idempotent, so run the command again. |

Every code above, with its remediation, is in [Error codes](https://docs.blobhub.io/cli/error-codes.md).

## See also

* [`blobhub workflow listeners`](https://docs.blobhub.io/cli/workflow/commands/listeners) — read the switch and the outcomes.
* [Listeners](https://docs.blobhub.io/blob-types/workflow/workflows/listeners.md#the-switch) — what the switch does on the platform.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.