Metadata-Version: 2.4
Name: cash4tokens
Version: 0.1.4
Summary: Provider CLI for cash4tokens.
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: packaging>=24.0
Requires-Dist: typer>=0.12.0
Requires-Dist: web3>=7.0.0
Requires-Dist: websockets>=13.0
Description-Content-Type: text/markdown

# cash4tokens CLI

The cash4tokens CLI turns a machine with Claude Code or Codex access into a provider node for `api.cash4tokens.com`.

## Install

```bash
pip install cash4tokens
```

For local development:

```bash
cd cli
pip install -e .
```

Editable installs are treated as local development builds and do not self-update automatically.

## Setup

```bash
cash4tokens init \
  --server https://api.cash4tokens.com \
  --email you@example.com
```

`cash4tokens init` now sends a 6-digit OTP to the account email, verifies it in the terminal, and then registers the machine as a provider. If the account is new, the CLI asks for a Base payout wallet before finishing setup.

If you omit `--wallet`, the CLI guides you through entering a valid Base payout wallet when needed. This writes `~/.cash4tokens/config.json`. The CLI does not need a `.env` file.

## Commands

| Command | Description |
|---------|-------------|
| `cash4tokens init` | Register this machine as a provider |
| `cash4tokens profile` | Show or update the account display name and payout wallet |
| `cash4tokens start` | Start the provider daemon in the foreground |
| `cash4tokens status` | Show server connectivity, provider connection state, balance, and total earnings |
| `cash4tokens dashboard` | Show recent served requests and your own spend |
| `cash4tokens version` | Show the installed CLI version and manifest URL |
| `cash4tokens self-update` | Fetch the release manifest and install the latest packaged CLI |
| `cash4tokens install` | Install the daemon as a macOS LaunchAgent |
| `cash4tokens uninstall` | Remove the macOS LaunchAgent |

## Auto-Update Behavior

- The manifest lives at `https://api.cash4tokens.com/manifest.json` by default.
- Packaged CLI installs poll the manifest on startup and periodically while the daemon is running.
- When a newer release is available, the CLI installs `cash4tokens==<version>` with `python -m pip`, then restarts itself when idle.
- Local source checkouts and editable installs skip automatic updates by design.

## Config File

Example `~/.cash4tokens/config.json`:

```json
{
  "server_url": "https://api.cash4tokens.com",
  "manifest_url": "https://api.cash4tokens.com/manifest.json",
  "provider_id": "uuid",
  "daemon_token": "dt_xxx",
  "api_key": "c4t_xxx",
  "user_id": "uuid",
  "wallet_address": "0x..."
}
```

The CLI also stores update check metadata under the `update` key after the first manifest fetch.

## Credential Sources

### Claude Code

- Reads OAuth tokens from the macOS Keychain
- Requires a Claude Code subscription on the local machine
- Tokens stay local and are refreshed by the local Claude tooling

### Codex

- Reads auth state from `~/.codex/auth.json`
- Requires an active Codex-capable OpenAI account on the local machine
- Tokens stay local and are refreshed through the existing OpenAI auth flow

## macOS LaunchAgent

`cash4tokens install` creates `~/Library/LaunchAgents/com.cash4tokens.daemon.plist`.

- Starts on login
- Restarts when network is available
- Writes logs to `~/.cash4tokens/log/daemon.log`
- Picks up new CLI releases automatically because `cash4tokens start` performs an update check before the daemon comes online

## Files

```text
cli/
  pyproject.toml              Publishable CLI package config
  cash4tokens_cli/
    main.py                  Typer command entrypoint
    daemon.py                Daemon lifecycle, update loop, and inference orchestration
    connection.py            WebSocket client with reconnects
    health.py                Capability discovery and heartbeat payloads
    provider/                Local Anthropic and OpenAI integrations
    token/                   Local auth token readers
    update.py                Manifest parsing and self-update flow
```
