---
name: logshq-streams
description: Use when users explicitly ask to create, publish, share, read, follow, inspect, or analyze Logshq streams or Logshq viewer URLs.
---

# Logshq Streams

Treat Logshq as an external upload destination. Upload only when the user explicitly asks. Never pipe secrets, credentials, private keys, or other sensitive data.

Streams are end-to-end encrypted. The `logshq` CLI encrypts before upload and decrypts on read; the server only ever holds ciphertext. The decryption key lives in the viewer URL's `#k=` fragment and never reaches the server — so the full URL (including the fragment) is itself the secret. Share it only with people who should read the stream, and never put it in logs or citations.

Streams are ephemeral: they expire about 5 minutes after their last output, and nothing is stored after that. Read or analyze a stream promptly; an expired stream reads back as "not found".

## Create a stream

Pipe the command's output through the CLI. It prints the viewer URL (with the `#k=` key) immediately, then streams encrypted output.

```bash
mix test 2>&1 | npx --yes logshq
```

Adapt only the streamed command (`mix test` above). Set `LOGSHQ_BASE_URL` to target another deployment; if unset it defaults to `https://logshq.com`. Print the viewer URL before ingestion finishes so it can be shared while output is live. A command failure can yield a nonzero status even if Logshq received the output.

## Read and analyze a stream

Pass the full viewer URL — fragment included — to `read`. The CLI fetches the ciphertext snapshot and decrypts it locally to stdout.

```bash
npx --yes logshq read "https://logshq.com/l/<id>#k=<key>"            # one snapshot
npx --yes logshq read "https://logshq.com/l/<id>#k=<key>" --follow   # poll until the stream ends
```

For a one-shot read, each invocation returns the complete decrypted output received so far; poll on your own cadence and deadline, then analyze the latest snapshot. `--follow` polls and prints new output until the stream reports it has ended.

The browser viewer is `GET /l/:id` (HTML plus WebSocket) and reads the key from the URL fragment. `GET /l/:id?format=text` returns raw **ciphertext** and is what `read` decrypts — do not scrape the HTML or expect readable text from it directly.

## Quick reference

| Need | Rule |
| --- | --- |
| Create | `your-command 2>&1 \| npx logshq` |
| Read once | `npx logshq read "<viewer-url>"` |
| Follow | `npx logshq read "<viewer-url>" --follow` |
| The key | Lives in the URL `#k=` fragment; never sent to the server |
| Lifetime | Streams expire ~5 minutes after their last output — read promptly |
| Snapshot endpoint | `GET /l/:id?format=text` returns ciphertext (the CLI decrypts it) |

Common mistakes: `PUT /` is not implemented — publishing goes through the CLI (`PUT /ingest/:id` under the hood). Never share or cite the `#k=` fragment. `format=text` is ciphertext, not readable text; decrypt it with `logshq read`.