sentrify 0.1.0

Sentrify — AI-powered cross-surface command execution

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

# 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

# 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

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

pip install sentrify

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

To point at a local brain instance during development:

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.