Metadata-Version: 2.4
Name: devin-cli
Version: 1.3.3
Summary: Unofficial CLI for Devin AI - The first AI Software Engineer
Project-URL: Homepage, https://github.com/revanthpobala/devin-cli
Project-URL: Repository, https://github.com/revanthpobala/devin-cli.git
Project-URL: Issues, https://github.com/revanthpobala/devin-cli/issues
Author-email: revanth <revanth@example.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,automation,autonomous,cli,cognition,devin,software-engineer,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer[all]>=0.9.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/revanthpobala/devin-cli/main/assets/logo.png" alt="Devin CLI Logo" width="300">
</p>

# Devin CLI (Unofficial) — The Professional Terminal Interface for Devin AI

<p align="center">
  <a href="https://pypi.org/project/devin-cli/"><img src="https://img.shields.io/pypi/v/devin-cli.svg?style=for-the-badge&color=0294DE" alt="PyPI version"></a>
  <a href="https://github.com/revanthpobala/homebrew-tap"><img src="https://img.shields.io/badge/Homebrew-Tap-orange?style=for-the-badge&logo=homebrew" alt="Homebrew Tap"></a>
  <a href="https://github.com/revanthpobala/devin-cli/actions/workflows/pypi-publish.yml"><img src="https://github.com/revanthpobala/devin-cli/actions/workflows/pypi-publish.yml/badge.svg" alt="Build Status"></a>
</p>

> **The first unofficial CLI for the world's first AI Software Engineer. Supports both the modern v3 API and the legacy v1 API with full multi-profile management.**

Devin CLI is designed for high-velocity engineering teams. It strips away the friction of the web UI, allowing you to orchestrate autonomous agents, manage complex contexts, and automate multi-step development workflows through a robust, terminal-first interface.

---

## ⚡ Quick Start

### 1. Installation

**Recommended: Via Homebrew (macOS)**
```bash
brew tap revanthpobala/tap
brew install devin-cli
```

**Via pipx (Isolated environment)**
```bash
pipx install devin-cli
```

**Via pip**
```bash
pip install devin-cli
```

### 2. Configuration
```bash
devin configure
# Paste your API token (apk_... or cog_...) from https://preview.devin.ai/settings
# Select API version: v3 (default) or v1 (legacy)
```

### 3. Your First Session
```bash
devin create-session "Identify and fix the race condition in our Redis cache layer"
devin watch
```

---

## Authentication & Usage

### AI Agent Integration (JSON Output)
For external automation and AI agent architectures relying on the CLI, `devin-cli` supports a global `--json` flag. This will suppress all visual output/terminal colors and instead uniformly return raw JSON objects for stdout and API errors, making the CLI completely deterministic to parse.
```bash
devin --json sessions create "My prompt"
# { "session_id": "...", "status": "running" }
```

### Multi-Profile Support

```bash
devin configure --profile personal
devin configure --profile service
devin --profile service sessions list
devin --profile personal sessions create "Fix the failing tests"
```

Profiles are stored in `~/.config/devin/config.json` — fully isolated including session caches and active session IDs.

---

## 🤖 All Commands

### Flat Commands (0.1.x style — quick access)

| Command | Description |
| :--- | :--- |
| `devin create-session "<prompt>"` | Create a new session |
| `devin watch` | Live-watch the active session |
| `devin status` | One-liner status of active session |
| `devin open` | Open active session URL in browser |
| `devin message "<text>"` | Send a message to active session |
| `devin message --file prompt.txt` | Send a message from file |
| `devin terminate` | Terminate active session |
| `devin list-sessions` | List recent sessions |
| `devin upload <file>` | Upload a file to Devin |
| `devin attach <file> "<prompt>"` | Upload file + start session with it |
| `devin list-knowledge` | List knowledge notes |
| `devin update-knowledge <id>` | Update a knowledge entry |
| `devin update-tags` | Update tags on a session |
| `devin history` | Show locally cached session ID |
| `devin messages` | Show conversation history |
| `devin get-session` | Show session details + structured output |
| `devin update-playbook <id>` | Update a playbook |
| `devin delete-playbook <id>` | Delete a playbook |
| `devin list-secrets` | List organization secrets |
| `devin delete-secret <id>` | Delete a secret |
| `devin chain` | Sequential playbook orchestration |
| `devin use <session_id>` | Switch active session |
| `devin configure` | Configure API token and profile |

### Sessions (`devin sessions <cmd>`)

| Command | Key Flags | Description |
| :--- | :--- | :--- |
| `create` | see below | Create a session |
| `list` | `--limit`, `--json` | List sessions |
| `get` | `[session_id]` | Get session details |
| `watch` | `--interval` | Live-watch with exponential backoff |
| `message` | `[text]`, `--file` | Send message or file to session |
| `messages` | `[session_id]` | Full conversation history |
| `terminate` | `[session_id]` | Terminate a session |
| `insights` | `[session_id]` | ACU / performance insights (v3) |
| `cost` | `[session_id]` | ACU consumption |

> **Note for Service Tokens (`cog_`):** When retrieving a specific session via `devin sessions get <id>`, the CLI automatically falls back to filtering the org-wide `sessions list` via a `?session_ids=[<id>]` query parameter to gracefully bypass the `403 Forbidden` error natively returned by the direct API endpoint for service accounts.

#### `sessions create` / `create-session` — Full Flag Reference

| Flag | Type | Description |
| :--- | :--- | :--- |
| `[prompt]` | arg | Task prompt |
| `--file`, `-f` | path | Read prompt from file |
| `--title`, `-t` | str | Session title |
| `--wait`, `-w` | flag | Block until session finishes |
| `--interval` | int | Polling interval for `--wait` (default: 5s) |
| `--max-acu` | int | ACU spend cap |
| `--force` | flag | Skip duplicate detection |
| `--advanced-mode` | str | `analyze` \| `create_playbook` \| `improve_playbook` \| `batch` \| `manage_knowledge` |
| `--playbook-id` | str | Playbook to apply (v3) |
| `--child-playbook-id` | str | Playbook for each sub-session in `batch` mode (v3) |
| `--bypass-approval` | flag | Skip UI approval — child sessions start immediately (v3) |
| `--tag` | str (repeatable) | Session tags |
| `--repo` | str (repeatable) | Repo URLs to attach (v3) |
| `--knowledge-id` | str (repeatable) | Knowledge IDs to inject |
| `--secret-id` | str (repeatable) | Secret IDs to inject (v3) |
| `--session-link` | str (repeatable) | Session URLs as context (v3) |
| `--attachment-url` | str (repeatable) | Attachment URLs (v3) |
| `--structured-output-schema` | str | JSON schema for structured response (v3) |
| `--create-as-user-id` | str | Enterprise: impersonate a user (v3) |
| `--org` | str | Override org ID |

#### Full Batch Automation Example
```bash
# No browser interaction required
devin sessions create \
  --advanced-mode batch \
  --playbook-id <orchestrator-id> \
  --child-playbook-id <worker-id> \
  --bypass-approval \
  "Process each file in the attached CSV"
```

### Knowledge (`devin knowledge <cmd>`)

| Command | Description |
| :--- | :--- |
| `list` | List all knowledge notes |
| `create` | Create a knowledge note |
| `delete <id>` | Delete a knowledge note |

### Playbooks (`devin playbooks <cmd>`)

| Command | Description |
| :--- | :--- |
| `list` | List all playbooks |
| `create` | Create a playbook |
| `update <id>` | Update a playbook |
| `delete <id>` | Delete a playbook |

### Secrets (`devin secrets <cmd>`)

| Command | Description |
| :--- | :--- |
| `list` | List organization secrets |
| `create` | Create a secret |
| `delete <id>` | Delete a secret |

### Schedules (`devin schedules <cmd>`)

| Command | Description |
| :--- | :--- |
| `list` | List schedules |
| `create` | Create a CRON schedule |

### Repositories (`devin repos <cmd>`)

| Command | Description |
| :--- | :--- |
| `list` | List indexed repositories |
| `index` | Force-index a repository |

### Attachments (`devin attachments <cmd>`)

| Command | Description |
| :--- | :--- |
| `upload <file>` | Upload a file |
| `download <id>` | Download an attachment |

### Enterprise (`devin enterprise <cmd>`)

| Command | Description |
| :--- | :--- |
| `whoami` | Show current identity |
| `list-orgs` | List accessible organizations |

### Chain (`devin chain`)

Orchestrate a sequential pipeline of playbooks:

```bash
# Inline
devin chain "Refactor utils.py" --playbooks "lint_check,unit_tests"

# YAML workflow file
devin chain --file workflow.yml
```

---

## 🛡 Session Deduplication

The CLI caches a SHA-256 hash of your last 50 prompts per profile. Duplicate prompts are caught before wasting ACUs:

```
Duplicate Detected: You recently created a session with this exact prompt.
Existing Session ID: abc123...
Are you sure you want to create a duplicate session? [y/N]
```

Use `--force` to bypass.

---

## 📟 CI/CD Integration

```yaml
env:
  DEVIN_API_TOKEN: ${{ secrets.DEVIN_API_TOKEN }}
  DEVIN_ORG_ID: ${{ secrets.DEVIN_ORG_ID }}
run: |
  devin create-session "Review PR #${{ github.event.pull_request.number }}" --wait
```

**Environment variables:**

| Variable | Description |
| :--- | :--- |
| `DEVIN_API_TOKEN` | API token (overrides config) |
| `DEVIN_ORG_ID` | Organization ID |
| `DEVIN_BASE_URL` | Override base URL |
| `DEVIN_API_VERSION` | Set `v1` or `v3` without configuring |

---

## 🕹 v1 / v3 Profile Compatibility

| Feature | v1 | v3 |
| :--- | :---: | :---: |
| Sessions (create, list, get, terminate) | ✅ | ✅ |
| Knowledge (create, update, delete) | ✅ | ✅ |
| Playbooks (create, update, delete) | ✅ | ✅ |
| Secrets (list, create, delete) | ✅ | ✅ |
| Attachments (upload, download) | ✅ | ✅ |
| Advanced Mode (`--advanced-mode`) | ⚠️ warned | ✅ |
| Batch sessions (`--bypass-approval`) | ⚠️ warned | ✅ |
| Session Insights | ❌ | ✅ |
| Schedules | ❌ | ✅ |
| Repositories | ❌ | ✅ |
| Enterprise endpoints | ❌ | ✅ |

> v3-only flags are accepted but ignored on v1 profiles — the CLI prints a clear warning listing exactly which flags were dropped.

---

## ⚙️ Engineering Specs

- **Architecture**: Full v3 API support (`v3beta1` + `enterprise`) + v1 legacy proxy
- **Config**: `~/.config/devin/config.json`
- **Platform**: Linux, macOS, WSL2
- **Python**: 3.9+

---

## 🧪 Developer Hub

```bash
pip install -e ".[dev]"
PYTHONPATH=src python3 -m pytest
```

---

## 📄 License

MIT. **Devin CLI** is an unofficial community project and is not affiliated with Cognition AI.
