Metadata-Version: 2.4
Name: synthkb-cli
Version: 0.5.2
Summary: Secure remote CLI for deterministic Synth Project evidence
Project-URL: Documentation, https://synthkb.dev/docs/reference/cli
Author-email: Gaby Tal <gaby@synthkb.ai>
License: Sustainable Use License v1.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: click<9,>=8.1.7
Requires-Dist: httpx<1,>=0.28
Requires-Dist: keyring<26,>=25.7
Description-Content-Type: text/markdown

# Synth CLI

`synthkb-cli` is the small, secure remote client for deterministic,
revision-bound evidence from a Synth Project. It does not install the Synth
server, generate answers, invoke an LLM, ingest sources, or mutate Projects.

Requires Python 3.11–3.14 and supports macOS, Linux, and Windows.

## Install

```bash
pipx install synthkb-cli
# or: uv tool install synthkb-cli
synth --version
```

## Connect and read evidence

Create a read-only `knowledge:read` API key in **Settings → API Keys**, then:

```bash
synth login https://synth.example.com
synth projects
synth use docs
synth search "authentication"
synth page PAGE_PATH --snapshot SNAPSHOT_ID
synth status
synth logout
```

Login verifies the server, key, compatibility, and optional Project before it
saves anything. The OS keychain is preferred; a private file backend is
available for headless environments.

For CI, keep secrets out of process arguments:

```bash
synth login https://synth.example.com \
  --api-key-file /run/secrets/synth-api-key \
  --project prj_docs \
  --credential-store file \
  --non-interactive \
  --json
```

Use `synth doctor --json` for redacted diagnostics. See the
[complete CLI reference](https://synthkb.dev/docs/reference/cli) and
[automation guide](https://synthkb.dev/docs/guides/cli-automation).

## Additional HTTP headers

For a server behind an access gateway, pass generic headers before the command:

```bash
synth \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \
  login https://synth.example.com
```

To apply the same headers to every command in a shell or CI job, use a JSON
object in `SYNTH_HTTP_HEADERS`:

```bash
export SYNTH_HTTP_HEADERS='{"X-Gateway-Client":"client","X-Gateway-Secret":"secret"}'
synth login https://synth.example.com
synth status
```

Additional headers are not saved in the Synth profile or printed by debug
output. `Authorization` and other headers owned by the CLI cannot be overridden.
