Metadata-Version: 2.4
Name: cablecat
Version: 0.2.0
Summary: TUI inspector for USB-C cables, eMarkers, and Power Delivery.
Project-URL: Homepage, https://github.com/xiaoran007/CableCat
Project-URL: Repository, https://github.com/xiaoran007/CableCat
Author: CableCat contributors
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: emarker,macos,thunderbolt,tui,usb-c,usb-pd
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Requires-Dist: textual>=0.85
Description-Content-Type: text/markdown

# CableCat

[![PyPI](https://img.shields.io/pypi/v/cablecat.svg)](https://pypi.org/project/cablecat/)
[![Python](https://img.shields.io/pypi/pyversions/cablecat.svg)](https://pypi.org/project/cablecat/)
[![Platform](https://img.shields.io/badge/platform-macOS%2014%2B%20arm64-blue)](#platform-support)
[![License](https://img.shields.io/badge/license-GPL--3.0--only-green.svg)](LICENSE)

CableCat is a terminal inspector for USB-C ports, cables, eMarkers, USB Power
Delivery, data speed, DisplayPort Alt Mode, USB4, and Thunderbolt-related state.

It opens as a TUI by default and gives each USB-C port a readable diagnosis:
what is connected, what the OS can observe, what the cable or partner appears to
declare, and which details are unavailable.

![CableCat demo](https://files.catbox.moe/773wmp.png)

## Install

CableCat is distributed through PyPI.

```bash
pipx install cablecat
```

You can also use `uv` or `pip`:

```bash
uv tool install cablecat
python -m pip install cablecat
```

## Quick Start

Open the inspector:

```bash
cablecat
```

Export a machine-readable snapshot:

```bash
cablecat --json
```

Include raw OS observations:

```bash
cablecat --json --raw
```

Refresh snapshots continuously:

```bash
cablecat --watch --json
```

## What CableCat Shows

CableCat is designed to answer practical questions quickly:

- Is this port empty, charging, carrying USB data, running DisplayPort Alt Mode,
  or doing several things at once?
- What USB speed is currently observable, such as High Speed, SuperSpeed, or
  SuperSpeed+?
- What USB-PD source power profiles are visible, and what is the advertised max?
- Was an eMarker observed, and what cable capabilities can be decoded from it?
- Is the connected partner likely a display, hub, peripheral, charger, AMA, or
  another PD product type?
- Which USB devices are attached below the port?
- Which facts are observed, decoded, inferred, unknown, or unavailable?

The TUI keeps the port list on the left and a readable diagnosis on the right.
The detail tabs expose overview, attached devices, decoded PD/VDO fields, raw OS
properties, and warnings.

## Important Limits

CableCat is read-only. It does not:

- sniff USB-PD traffic;
- send Discover Identity or other active PD messages;
- load a helper driver;
- claim to verify cable electrical quality.

CableCat reports declared capabilities and OS-observed state. A cable can claim
support for a speed or current rating and still fail a real signal-integrity or
power test. Use a hardware tester when you need electrical validation.

On macOS, some eMarker information may only appear when the system decides it
needs it, such as for cables above 3A, USB4, or Thunderbolt scenarios. When the
OS does not expose a field, CableCat marks it as unavailable instead of guessing.

## Platform Support

Current CableCat focuses on Apple Silicon macOS 14+.

| Platform | Status |
| --- | --- |
| macOS 14+ arm64 | Supported first. Uses a bundled Swift/IOKit probe. |
| Linux | Adapter placeholder only. Future target: `/sys/class/typec`. |
| Windows | Adapter placeholder only. Future target: UCSI, SetupAPI, or WMI. |

## CLI Reference

```bash
cablecat                 # open the TUI
cablecat --json          # print normalized JSON
cablecat --json --raw    # include raw OS probe data
cablecat --watch --json  # stream refreshed JSON snapshots
cablecat --version       # print version
cablecat --help          # show all options
```

The JSON output contains stable high-level sections for diagnosis,
capabilities, decoded PD/VDO fields, and raw observations when requested.

## Development

CableCat uses Python for the CLI/TUI and decoding layers, plus a SwiftPM-built
macOS dynamic library for the IOKit probe.

Common commands:

```bash
make test
make build
make push
```

`make build` runs:

```bash
.venv/bin/python -m build --outdir dist
```

On macOS arm64, `python -m build` invokes the Hatchling build hook, builds
`libCableCatMacOSProbe.dylib` with SwiftPM, and includes it in the wheel at:

```text
cablecat/native/macos/libCableCatMacOSProbe.dylib
```

The resulting macOS wheel is tagged like:

```text
py3-none-macosx_14_0_arm64
```

## License And Prior Art

CableCat is licensed under GPL-3.0-only.

[WhatCable](https://github.com/darrylmorley/whatcable) is useful prior art for
product behavior and presentation, but CableCat does not copy WhatCable
implementation code. CableCat treats WhatCable's public repository only as a
behavioral reference because its license note describes mixed MIT/proprietary
source boundaries.
