orpheus-cli 0.1.1__tar.gz

orpheus_cli-0.1.1/.gitignore

@@ -0,0 +1,20 @@
+*.egg-info/
+**/__pycache__/
+**/node_modules/
+**/.vscode/
+*.code-workspace
+.claude/*
+!.claude/skills/
+.mcp.json
+instructions.md
+.float/designer.md
+.float/doc.md
+.float/messages.jsonl
+build/
+.env
+old
+client/screenshots
+client/screenshot-*
+client/dist/
+client/src/data
+**/.DS_STORE

orpheus_cli-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

orpheus_cli-0.1.1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: orpheus-cli
+Version: 0.1.1
+Summary: A command-line interface for orchestrating AI agents
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=14.3.2
+Requires-Dist: typer>=0.21.1
+Description-Content-Type: text/markdown
+
+# Orpheus CLI
+
+Command-line interface for Orpheus by [Fulcrum](https://fulcrum.inc/).

orpheus_cli-0.1.1/README.md

@@ -0,0 +1,3 @@
+# Orpheus CLI
+
+Command-line interface for Orpheus by [Fulcrum](https://fulcrum.inc/).

orpheus_cli-0.1.1/orpheus/__init__.py

@@ -0,0 +1 @@
+"""Orpheus CLI."""

orpheus_cli-0.1.1/orpheus/auth.py

@@ -0,0 +1,94 @@
+"""GitHub device flow authentication."""
+
+import time
+
+import httpx
+from pydantic import BaseModel, HttpUrl
+
+from orpheus.config import get_config
+
+
+class AuthError(Exception):
+    """Authentication failed."""
+
+    pass
+
+
+class DeviceCodeResponse(BaseModel):
+    device_code: str
+    user_code: str
+    verification_uri: HttpUrl
+    expires_in: int
+    interval: int
+
+
+class AccessTokenResponse(BaseModel):
+    access_token: str
+    token_type: str
+    scope: str
+
+
+class ErrorResponse(BaseModel):
+    error: str
+    error_description: str | None = None
+    interval: int | None = None
+
+    def check(self) -> int:
+        """Return interval for retryable errors, raise AuthError for fatal."""
+        match self.error:
+            case "authorization_pending":
+                return self.interval or 5
+            case "slow_down":
+                return self.interval or 10
+            case "expired_token":
+                raise AuthError("Device code expired. Please try again.")
+            case "access_denied":
+                raise AuthError("Authorization denied by user.")
+            case _:
+                raise AuthError(f"Unexpected error: {self.error}")
+
+
+TokenResponse = AccessTokenResponse | ErrorResponse
+
+
+def parse_token_response(data: dict) -> TokenResponse:
+    """Parse GitHub's token endpoint response."""
+    if "access_token" in data:
+        return AccessTokenResponse.model_validate(data)
+    return ErrorResponse.model_validate(data)
+
+
+def request_device_code() -> DeviceCodeResponse:
+    """Request a device code from GitHub."""
+    config = get_config()
+    response = httpx.post(
+        "https://github.com/login/device/code",
+        data={"client_id": config.github_client_id},
+        headers={"Accept": "application/json"},
+    )
+    response.raise_for_status()
+    return DeviceCodeResponse.model_validate(response.json())
+
+
+def poll_for_user_access_token(device_code: str, interval: int) -> str:
+    """Poll GitHub until user authorizes, then return user access token."""
+    config = get_config()
+
+    while True:
+        response = httpx.post(
+            "https://github.com/login/oauth/access_token",
+            data={
+                "client_id": config.github_client_id,
+                "device_code": device_code,
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+            },
+            headers={"Accept": "application/json"},
+        )
+        response.raise_for_status()
+
+        match parse_token_response(response.json()):
+            case AccessTokenResponse(access_token=token):
+                return token
+            case ErrorResponse() as error:
+                interval = error.check()
+                time.sleep(interval)

orpheus_cli-0.1.1/orpheus/client.py

@@ -0,0 +1,201 @@
+"""HTTP client for Orpheus server API."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from pydantic import HttpUrl
+
+from orpheus.config import load_config
+
+
+if TYPE_CHECKING:
+    from orpheus.config import Config
+
+
+class NotFoundError(Exception):
+    """Raised when a resource is not found."""
+
+    def __init__(self, resource_type: str, identifier: str):
+        self.resource_type = resource_type
+        self.identifier = identifier
+        super().__init__(f"{resource_type} '{identifier}' not found")
+
+
+class APIError(Exception):
+    """Raised when an API request fails."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class OrpheusClient:
+    """Orpheus API client."""
+
+    def __init__(self, config: Config | None = None):
+        self.config = config or load_config()
+        self._client = httpx.Client(base_url=str(self.base_url), timeout=300)
+
+    @property
+    def base_url(self) -> HttpUrl:
+        """Base URL for the Orpheus API."""
+        return self.config.base_url
+
+    @property
+    def user_access_token(self) -> str | None:
+        """User access token for the Orpheus API."""
+        return self.config.user_access_token
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        """Headers for API requests."""
+        headers = {}
+        if self.user_access_token:
+            headers["Authorization"] = f"Bearer {self.user_access_token}"
+        return headers
+
+    def create_task(
+        self,
+        spec: str,
+        repo_full_name: str,
+        snapshot_id: str | None = None,
+        programs: list[str] | None = None,
+        git_branch: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new task."""
+        body: dict[str, Any] = {"spec": spec, "repo_full_name": repo_full_name}
+        if snapshot_id:
+            body["snapshot_id"] = snapshot_id
+        if programs:
+            body["programs"] = programs
+        if git_branch:
+            body["git_branch"] = git_branch
+        response = self._client.post("/tasks", json=body, headers=self._headers)
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response.json()
+
+    def get_task(self, task_slug: str) -> dict[str, Any]:
+        """Get task details by slug."""
+        response = self._client.get(f"/tasks/{task_slug}", headers=self._headers)
+        if response.status_code == 404:
+            raise NotFoundError("Task", task_slug)
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response.json()
+
+    def stop_task(self, task_slug: str) -> dict[str, Any]:
+        """Stop a task by slug."""
+        response = self._client.delete(f"/tasks/{task_slug}", headers=self._headers)
+        if response.status_code == 404:
+            raise NotFoundError("Task", task_slug)
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response.json()
+
+    def list_tasks(self, active_only: bool = True) -> list[dict[str, Any]]:
+        """List tasks."""
+        params = {} if active_only else {"active_only": "false"}
+        response = self._client.get("/tasks", headers=self._headers, params=params)
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response.json()["tasks"]
+
+    def get_execution_diff(self, execution_slug: str) -> str:
+        """Get diff for an execution by slug."""
+        response = self._client.get(f"/executions/{execution_slug}/diff", headers=self._headers)
+        if response.status_code == 404:
+            raise NotFoundError("Execution", execution_slug)
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response.json()["diff"]
+
+    def list_repos(self) -> list[dict[str, Any]]:
+        """List accessible repositories."""
+        response = self._client.get("/repos", headers=self._headers)
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response.json()["repos"]
+
+    def start_setup(self, repo_full_name: str, private: bool) -> dict[str, Any]:
+        """Start devbox setup for a repository."""
+        response = self._client.post(
+            "/setup/start",
+            json={"repo_full_name": repo_full_name, "private": private},
+            headers=self._headers,
+        )
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response.json()
+
+    def save_setup(self, repo_full_name: str) -> dict[str, Any]:
+        """Save devbox state by creating a snapshot."""
+        response = self._client.post(
+            "/setup/save",
+            json={"repo_full_name": repo_full_name},
+            headers=self._headers,
+        )
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response.json()
+
+    def download_file(
+        self,
+        path: str,
+        repo: str | None = None,
+        execution_slug: str | None = None,
+        agent_name: str | None = None,
+    ) -> httpx.Response:
+        """Download a file from a VM. Returns the raw response for streaming."""
+        params: dict[str, str] = {"path": path}
+        if repo:
+            params["repo"] = repo
+        if execution_slug:
+            params["execution_slug"] = execution_slug
+        if agent_name:
+            params["agent_name"] = agent_name
+        response = self._client.get("/files/download", params=params, headers=self._headers)
+        if response.status_code == 404:
+            raise NotFoundError("File", path)
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response
+
+    def upload_file(
+        self,
+        local_path: Path | None,
+        remote_path: str,
+        content: bytes | None = None,
+        repo: str | None = None,
+        execution_slug: str | None = None,
+        agent_name: str | None = None,
+    ) -> dict[str, Any]:
+        """Upload a file to a VM."""
+        params: dict[str, str] = {"path": remote_path}
+        if repo:
+            params["repo"] = repo
+        if execution_slug:
+            params["execution_slug"] = execution_slug
+        if agent_name:
+            params["agent_name"] = agent_name
+
+        if content is not None:
+            file_data = content
+            filename = Path(remote_path).name
+        elif local_path:
+            file_data = local_path.read_bytes()
+            filename = local_path.name
+        else:
+            raise ValueError("Either local_path or content must be provided")
+
+        response = self._client.post(
+            "/files/upload",
+            params=params,
+            files={"file": (filename, file_data)},
+            headers=self._headers,
+        )
+        if response.status_code != 200:
+            raise APIError(response.text)
+        return response.json()

orpheus_cli-0.1.1/orpheus/commands/auth.py

@@ -0,0 +1,85 @@
+"""Authentication commands."""
+
+import webbrowser
+
+import typer
+from orpheus.auth import AuthError, poll_for_user_access_token, request_device_code
+from orpheus.config import load_config, save_config
+from orpheus.display import console, print_error, print_success
+
+
+auth = typer.Typer(help="Manage authentication.", no_args_is_help=True)
+
+
+def has_browser() -> bool:
+    """Check if a browser is available."""
+    try:
+        webbrowser.get()
+        return True
+    except webbrowser.Error:
+        return False
+
+
+def _prompt_app_installation(app_slug: str) -> None:
+    """Print the installation link so the user can add the app to their repos."""
+    install_url = f"https://github.com/apps/{app_slug}/installations/new"
+    console.print()
+    console.print("Install the Orpheus GitHub App on any repos you want agents to work on:")
+    console.print(f"  {install_url}")
+    console.print()
+
+
+@auth.command()
+def login():
+    """Authenticate with Orpheus via GitHub."""
+    config = load_config()
+
+    # Request device code
+    response = request_device_code()
+
+    # Prompt user
+    console.print(f"Your one-time code is [bold green]{response.user_code}[/bold green]")
+    console.print()
+
+    if has_browser():
+        console.print("Press Enter to open `github.com` in your browser...")
+        input()
+        webbrowser.open(str(response.verification_uri))
+    else:
+        console.print(f"Open this URL in a browser: [bold blue]{response.verification_uri}[/bold blue]")
+        console.print("Enter the code above, then authorize the application.")
+        console.print()
+
+    # Poll for token
+    console.print("Waiting for authorization...")
+    try:
+        user_access_token = poll_for_user_access_token(response.device_code, response.interval)
+    except AuthError as error:
+        print_error(str(error))
+        raise typer.Exit(1)
+
+    # Save
+    config.user_access_token = user_access_token
+    save_config(config)
+    print_success("Authenticated successfully.")
+
+    _prompt_app_installation(config.github_app_slug)
+
+
+@auth.command()
+def logout():
+    """Clear stored credentials."""
+    config = load_config()
+    config.user_access_token = None
+    save_config(config)
+    print_success("Logged out.")
+
+
+@auth.command()
+def status():
+    """Show current authentication status."""
+    config = load_config()
+    if config.user_access_token:
+        print_success("Authenticated.")
+    else:
+        print_error("Not authenticated. Run `orpheus auth login`.")

orpheus_cli-0.1.1/orpheus/commands/setup.py

@@ -0,0 +1,132 @@
+"""Setup commands for devbox configuration."""
+
+from pathlib import Path
+
+import questionary
+import typer
+from orpheus.client import APIError, OrpheusClient
+from orpheus.config import get_config
+from orpheus.display import console, print_error, print_success, print_warning
+from orpheus.git import get_repo_from_cwd
+
+
+setup = typer.Typer(help="Manage devbox setup.", no_args_is_help=True)
+
+
+def get_keys_dir() -> Path:
+    """Get the directory for SSH keys."""
+    keys_dir = Path.home() / ".orpheus" / "keys"
+    keys_dir.mkdir(parents=True, exist_ok=True)
+    return keys_dir
+
+
+@setup.command()
+def start():
+    """Start devbox setup by selecting a repository."""
+    config = get_config()
+
+    if not config.user_access_token:
+        print_error("Not authenticated. Run 'orpheus auth login' first.")
+        raise typer.Exit(1)
+
+    client = OrpheusClient(config)
+
+    console.print("Fetching your repositories...")
+    try:
+        repos = client.list_repos()
+    except APIError as e:
+        print_error(f"Failed to fetch repos: {e}")
+        raise typer.Exit(1)
+
+    if not repos:
+        print_error("No repositories found.")
+        raise typer.Exit(1)
+
+    # Try to auto-detect repo from cwd
+    detected_repo = get_repo_from_cwd()
+    selected = None
+
+    if detected_repo:
+        selected = next((r for r in repos if r["full_name"] == detected_repo), None)
+        if selected:
+            console.print(f"Detected repository: [bold]{detected_repo}[/bold]")
+        else:
+            print_error(f"Detected repo '{detected_repo}' not in your accessible repos.")
+            raise typer.Exit(1)
+
+    if not selected:
+        choices = [questionary.Choice(title=r["full_name"], value=r) for r in repos]
+        selected = questionary.select(
+            "Select a repository:",
+            choices=choices,
+            use_shortcuts=False,
+            use_arrow_keys=True,
+            use_jk_keys=False,
+            use_search_filter=True,
+        ).ask()
+
+    if selected is None:
+        raise typer.Exit(1)
+
+    repo_full_name = selected["full_name"]
+    is_private = selected["private"]
+
+    console.print()
+    console.print(f"Provisioning devbox for [bold]{repo_full_name}[/bold]...")
+
+    try:
+        data = client.start_setup(repo_full_name, is_private)
+    except APIError as e:
+        print_error(f"Failed to start setup: {e}")
+        raise typer.Exit(1)
+
+    # Save SSH key
+    keys_dir = get_keys_dir()
+    key_path = keys_dir / data["instance_id"]
+    key_path.write_text(data["ssh_private_key"])
+    key_path.chmod(0o600)
+
+    # Display SSH info
+    console.print()
+    print_success("Your devbox is ready!")
+    console.print()
+    console.print("[bold]SSH command:[/bold]")
+    console.print(f"  ssh -i {key_path} {data['ssh_user']}@{data['ssh_host']}")
+    console.print()
+    console.print("[bold]Or use password:[/bold]")
+    console.print(f"  {data['ssh_password']}")
+    console.print()
+    print_warning("When you're done configuring, run:")
+    console.print("  [bold]orpheus setup save[/bold]")
+
+
+@setup.command()
+def save():
+    """Save devbox state by creating a snapshot."""
+    config = get_config()
+
+    if not config.user_access_token:
+        print_error("Not authenticated. Run 'orpheus auth login' first.")
+        raise typer.Exit(1)
+
+    # Detect repo from cwd
+    repo_full_name = get_repo_from_cwd()
+    if not repo_full_name:
+        print_error("Not in a git repository with a GitHub remote.")
+        print_error("Run this command from within your cloned repo directory.")
+        raise typer.Exit(1)
+
+    client = OrpheusClient(config)
+
+    console.print(f"Saving devbox snapshot for [bold]{repo_full_name}[/bold]...")
+
+    try:
+        data = client.save_setup(repo_full_name)
+    except APIError as e:
+        print_error(f"Failed to save devbox: {e}")
+        raise typer.Exit(1)
+
+    print_success(f"Snapshot saved: {data['snapshot_id']}")
+    console.print()
+    console.print("You can now run tasks with:")
+    console.print("  [bold]orpheus exec spec.txt[/bold]")

orpheus_cli-0.1.1/orpheus/config.py

@@ -0,0 +1,47 @@
+"""Configuration management for `~/.orpheus/config.json`."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pydantic import HttpUrl
+from pydantic_settings import BaseSettings
+
+
+_config: Config | None = None
+
+
+class Config(BaseSettings):
+    """Orpheus CLI configuration."""
+
+    base_url: HttpUrl = "https://api.orpheus.dev"
+    github_client_id: str = "Iv23liwHHi6oub0QWFau"
+    github_app_slug: str = "orpheus-app"
+    user_access_token: str | None = None
+
+
+def get_config() -> Config:
+    """Get the configuration."""
+    global _config
+    if _config is None:
+        _config = load_config()
+    return _config
+
+
+def load_config() -> Config:
+    """Load config from `~/.orpheus/config.json`."""
+    home = Path.home()
+    config_path = home / ".orpheus" / "config.json"
+    if config_path.exists():
+        data = json.loads(config_path.read_text())
+        return Config(**data)
+    return Config()
+
+
+def save_config(config: Config) -> None:
+    """Save config to `~/.orpheus/config.json`."""
+    home = Path.home()
+    config_path = home / ".orpheus" / "config.json"
+    config_path.parent.mkdir(exist_ok=True)
+    config_path.write_text(config.model_dump_json(indent=2))

orpheus_cli-0.1.1/orpheus/display.py

@@ -0,0 +1,21 @@
+"""Display helpers using Rich."""
+
+from rich.console import Console
+
+
+console = Console()
+
+
+def print_success(message: str) -> None:
+    """Print a success message."""
+    console.print(f"[green]✓[/green] {message}")
+
+
+def print_error(message: str) -> None:
+    """Print an error message."""
+    console.print(f"[red]✗[/red] {message}")
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message."""
+    console.print(f"[yellow]![/yellow] {message}")

orpheus_cli-0.1.1/orpheus/git.py

@@ -0,0 +1,39 @@
+"""Git helpers for the Orpheus CLI."""
+
+import re
+import subprocess
+
+
+def get_repo_from_cwd() -> str | None:
+    """Get GitHub repo (user/repo) from current directory's git remote.
+
+    Returns None if not in a git repo or origin remote is not GitHub.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        url = result.stdout.strip()
+    except subprocess.CalledProcessError:
+        return None
+
+    # Parse GitHub URLs:
+    # - https://github.com/user/repo.git
+    # - https://github.com/user/repo
+    # - git@github.com:user/repo.git
+    # - git@github.com:user/repo
+
+    # HTTPS pattern
+    https_match = re.match(r"https://github\.com/([^/]+)/([^/]+?)(?:\.git)?$", url)
+    if https_match:
+        return f"{https_match.group(1)}/{https_match.group(2)}"
+
+    # SSH pattern
+    ssh_match = re.match(r"git@github\.com:([^/]+)/([^/]+?)(?:\.git)?$", url)
+    if ssh_match:
+        return f"{ssh_match.group(1)}/{ssh_match.group(2)}"
+
+    return None