# ctx.cat CLI

`@synthlabs/ctx-cat-client@0.4.11` is the public package for `ctxcat` and
`ctxcat-mcp`. Its published package bytes are MIT-licensed; the source
repository remains private.

## Install

Prerequisites are Node.js 22 or newer, Bun 1.3.13, and a PATH-visible Bun
executable:

```bash
bun add --global @synthlabs/ctx-cat-client@0.4.11 && command -v ctxcat >/dev/null && command -v ctxcat-mcp >/dev/null
```

Direct Git dependency installation is not a supported installation contract.

## Continue A Portable Codex 0.147 Session

When a private reader link contains an authenticated portable Codex 0.147
transcript, the hosted reader shows **Continue in Codex**. Review the logical
transcript first, then use that control to copy a command shaped like:

```bash
bunx --package @synthlabs/ctx-cat-client@0.4.11 ctxcat codex continue --from-clipboard --handoff-nonce=<22-char-nonce>
```

Paste the command unchanged into the desired local workspace. The plain text
does not contain the reader URL; the same clipboard item carries that
capability in a nonce-bound structured representation. The CLI verifies the
share, creates or recovers a recipient-owned Codex 0.147 continuation, and
launches `codex resume` locally. If structured clipboard access is unavailable,
the reader fails honestly instead of copying the capability into shell history.

Client 0.4.11 enables public Codex 0.147 sender emission only for official
interactive Codex TUI paginated lineages. `codex exec` emits legacy history;
other headless sessions are unsupported. The retained
Codex 0.144.4 handoff below remains a separate path.

## Share And Resume An Exact Codex 0.144.4 Session

The retained exact-session path is pinned to official Codex CLI 0.144.4.
Replace `<full-codex-session-id>` with the exact ID from
`ctxcat sessions scan --json`. Run the sender command in a user-controlled
terminal:

```bash
ctxcat share <full-codex-session-id>
```

The command prints an encrypted reader link. Copy it only to the intended
teammate. The recipient needs authenticated, PATH-visible `codex-cli 0.144.4`
and an owned `CODEX_HOME` directory with mode `0700`. After copying the reader
link, run this from the desired workspace:

```bash
ctxcat resume
```

`ctxcat resume` reads the link from the clipboard, creates or recovers one
recipient-owned child, and launches `codex resume` in the current directory.
The reader URL is a capability; do not place it in model-visible arguments or
logs.

## For Automation

The lower-level commands are for a user-controlled automation that needs a
durable recovery file. Keep the file in a private directory; it contains reader
and owner lifecycle capabilities. Do not put a reader URL in command arguments,
model-visible input, or logs.

```bash
SESSION_ID='<full-codex-session-id>'; RECOVERY_DIR="$HOME/.local/share/ctxcat/$(date +%s)-$$-$RANDOM-$RANDOM"; install -d -m 700 "$RECOVERY_DIR" && ctxcat sessions share "$SESSION_ID" --capability-output "$RECOVERY_DIR/codex-handoff.recovery.json" --reveal-reader-url
# macOS
pbpaste | ctxcat resume --from-stdin --json
# Linux Wayland
wl-paste --no-newline | ctxcat resume --from-stdin --json
# Portable: save only the reader URL in this 0600 local file with a local editor.
READER_FILE="$RECOVERY_DIR/reader-url"
install -m 600 /dev/null "$READER_FILE"
ctxcat resume --from-stdin --json < "$READER_FILE"
```

## Share A File

Every create needs a fresh recovery path in a private directory:

```bash
RECOVERY_DIR="$HOME/.local/share/ctxcat/$(date +%s)-$$-$RANDOM-$RANDOM"
install -d -m 700 "$RECOVERY_DIR"
ctxcat file share ./notes.md --capability-output "$RECOVERY_DIR/notes.recovery.json"
```

The recovery file contains reader and owner lifecycle capabilities. Keep it out
of agent context, output, and logs, and never overwrite or reuse it for another
share.

## Read And Inspect

```bash
ctxcat fetch 'https://www.ctx.cat/<id>#<key>'
ctxcat fetch 'https://www.ctx.cat/<id>#<key>' --json
ctxcat meta 'https://www.ctx.cat/<id>#<key>' --json
```

`fetch --json` reads or decrypts content locally and includes its
`verification` result. `meta --json` returns server-visible storage metadata;
it does not decrypt content or independently verify the share.

## Lifecycle

Use the recovery file from the corresponding create command:

```bash
CAPABILITY_INPUT="${RECOVERY_DIR:?initialize RECOVERY_DIR first}/codex-handoff.recovery.json"
ctxcat lifecycle read --capability-input "$CAPABILITY_INPUT"
ctxcat lifecycle update --capability-input "$CAPABILITY_INPUT" --expires-at never
printf '%s' 'ready for review' | ctxcat lifecycle comment --capability-input "$CAPABILITY_INPUT" --from-stdin
ctxcat lifecycle comments --capability-input "$CAPABILITY_INPUT"
ctxcat lifecycle delete --capability-input "$CAPABILITY_INPUT"
```

`lifecycle update` changes expiry only. If a mutation was dispatched or accepted
but its response could not be completed, inspect the share and never retry that
mutation automatically.