# ctx.cat CLI

`@synthlabs/ctx-cat-client@0.3.1` 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.3.1 && command -v ctxcat >/dev/null && command -v ctxcat-mcp >/dev/null
```

Direct Git dependency installation is not a supported installation contract.

## Share And Resume A Codex Session

The accepted native continuation 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.