Metadata-Version: 2.4
Name: sentrify
Version: 0.1.0
Summary: Sentrify — AI-powered cross-surface command execution
License: Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: tomlkit>=0.12
Requires-Dist: rich>=13.0
Dynamic: license-file

# Sentrify CLI

> Type a command. The right surface executes it.

---

## Overview

Sentrify CLI is the terminal input channel for the Sentrify system. It takes a natural-language command, sends it to the Sentrify Brain, and the brain routes it to whichever surface — Mac, browser, or mobile — is the right executor for the job.

The CLI knows nothing about routing or execution logic. It speaks to the brain, the brain decides what runs and where.

---

## Usage

```bash
# One-shot command
sentrify "organize my downloads folder"
sentrify "open YouTube in the browser"
sentrify "send a text to John saying I'm on my way"

# Interactive chat mode
sentrify --chat

# Dry run — show the full execution plan without making any changes
sentrify "delete all .log files in /tmp" --dry-run

# Skip all confirmation prompts (for scripting)
sentrify "move budget.xlsx to ~/Documents/Finance" --yes

# Verbose output — show step-by-step execution detail
sentrify "list files in downloads" --verbose
```

---

## Authentication

```bash
# Store your API key
sentrify auth login

# Confirm the stored key
sentrify auth status

# Remove the stored key
sentrify auth logout
```

API keys are stored securely in the platform config directory (`platformdirs`) — never in environment variables or dotfiles.

---

## Flags

| Flag | Description |
| :--- | :--- |
| `--chat` | Start an interactive multi-turn session |
| `--dry-run` | Execute read-only steps, show write plan, make no changes |
| `--yes` | Skip all confirmation prompts |
| `--verbose` | Show detailed step output |
| `--version` | Print the installed version |

---

## How It Works

```mermaid
sequenceDiagram
    autonumber
    participant CLI
    participant Brain
    participant Surface

    CLI->>Brain: POST /v1/intent { message }
    Brain->>Brain: classify surface + plan phase 1
    Brain-->>CLI: plan { surface, steps, is_final_phase }

    CLI->>Surface: execute steps locally
    Surface-->>CLI: step results

    alt is_final_phase: false
        CLI->>Brain: POST /v1/sessions/{id}/results
        Brain->>Brain: replan with real executor data
        Brain-->>CLI: next phase plan
    end
```

Multi-phase tasks — where the brain needs real-world data before it can plan the next step — loop automatically. The CLI executes, reports results back to the brain, and receives the grounded next phase plan until `is_final_phase: true`.

---

## Dry Run

Any command containing write operations shows a full plan preview before executing. `--dry-run` takes this further: read-only steps run for real (so the brain gets actual filesystem data to plan against), write steps are shown but never executed.

```
Dry run  ·  Phase 1 of 2
────────────────────────────────────────
  [1] read_directory            path=/Users/dev/Downloads
  [2] create_folder             path=/Users/dev/Downloads/Images
  [3] move_file                 source=photo.jpg  destination=.../Images/photo.jpg
  [4] move_file                 source=wallpaper.png  destination=.../Images/wallpaper.png

⚠  Dry run — no changes made. Remove --dry-run to execute.
```

---

## Install

```bash
pip install sentrify
```

Requires Python 3.11+. The `sentrify` command is available immediately after install.

To point at a local brain instance during development:

```bash
export SENTRIFY_BRAIN_URL=http://localhost:8000
sentrify "list files in downloads"
```

---

## Project Structure

```
sentrify/
├── cli.py                      Entry point — Click group, run + auth commands
├── config.py                   Brain URL, API key header, timeout constants
├── models.py                   Pydantic schemas — IntentResponse · ExecutionPlan · PhaseResult
├── output.py                   Rich terminal rendering — steps, results, plan preview
├── auth/
│   ├── store.py                API key persistence via platformdirs + TOML
│   └── commands.py             sentrify auth login / logout / status
├── client/
│   └── brain.py                Async HTTP client — /v1/intent · /v1/sessions/{id}/results
└── executor/
    ├── runner.py               Execution loop — phases, dry-run, confirmation, results
    └── capabilities/
        ├── base.py             BaseCapability — readonly + requires_confirmation flags
        ├── files.py            read_directory · read_file · write_file · move · copy · rename · remove · create_folder · get_file_info
        ├── search.py           find_files · search_in_files
        └── shell.py            run_command
```

---

## Phase 2

When the Sentrify Mac agent ships — a persistent headless background process — the CLI becomes a pure input channel. Commands fire to the brain and return immediately. The background agent executes the plan independently, even after the terminal is closed.

---

*Proprietary and confidential. All rights reserved.*
