ocea 2.2.1
CLI interface for managing DigitalOcean droplets with local inventory tracking.
Requires Python: >=3.12
Keywords: digitalocean, cli, droplet, snapshot, cloud

====
OCEA
====

**OCEA** - DigitalOcean CLI with Local Inventory

A command-line interface for managing DigitalOcean droplets with local SQLite-based
inventory tracking. OCEA enables smart droplet management including automatic
snapshot-based restore, reserved IP reassignment, and comprehensive audit logging.

Features
========

* **Local Inventory Tracking**: SQLite database stores droplet metadata, snapshots,
  and reserved IPs locally for offline access and faster operations.

* **Smart Restore**: Automatically restore terminated droplets from snapshots using
  stored configuration (region, size, reserved IPs).

* **Audit Logging**: All operations are logged with timestamps for accountability
  and debugging.

* **Multi-Droplet Operations**: Manage multiple droplets in a single command.

* **Reserved IP Management**: Automatic reassignment of reserved (floating) IPs
  during restore operations.

* **In-Progress Tracking**: See snapshots that are currently being created.

* **Python API**: Programmatic access to all functionality.

Installation
============

Install from source::

    pip install -e .

For development::

    pip install -e ".[dev]"

Configuration
=============

OCEA requires a DigitalOcean API token. Configure it using one of these methods
(in priority order):

1. **`.env` file** in the current directory::

    DO_API_TOKEN=your_token_here

2. **Environment Variable** (recommended)::

    export DO_API_TOKEN=your_token_here
    # or
    export DIGITALOCEAN_TOKEN=your_token_here

3. **Config file** at ``~/.config/ocea/token`` (Linux/macOS) or
   ``%APPDATA%\ocea\token`` (Windows)

Optional: Set a custom database path::

    export OCEA_DB_PATH=/path/to/ocea.db

Quick Start
===========

::

    # Set your API token
    export DO_API_TOKEN=your_token_here

    # List all droplets
    ocea list

    # Check inventory status
    ocea status

    # Create a new droplet
    ocea new my-server -r nyc1 -s s-1vcpu-1gb -i ubuntu-24-04-x64

    # Create a snapshot
    ocea snap create my-server

    # Gracefully shut down
    ocea down my-server

    # Terminate with auto-snapshot (for cost savings)
    ocea down my-server --terminate

    # Restore from snapshot
    ocea up my-server

Commands
========

list
----

List droplets and snapshots from DigitalOcean API::

    ocea list                      # All droplets and snapshots
    ocea list --droplets           # Only droplets
    ocea list --snaps              # Only snapshots
    ocea list -r nyc1              # Filter by region
    ocea list -r nyc1 -r sfo3      # Filter by multiple regions
    ocea list --local              # From local database only
    ocea list --json               # Output as JSON

status
------

Show inventory summary or specific droplet details::

    ocea status                    # Summary of all droplets
    ocea status my-server          # Details for specific droplet
    ocea status --local            # From local database only
    ocea status --json             # Output as JSON

up
--

Power on droplets or restore from snapshots. OCEA automatically determines the
correct action based on the droplet's state:

* If the droplet is off: powers it on
* If the droplet is archived (terminated): restores from the most recent snapshot

::

    ocea up my-server              # Power on or restore
    ocea up server1 server2        # Multiple droplets
    ocea up --no-attach-ip srv     # Skip reserved IP reassignment
    ocea up --json my-server       # Output as JSON

down
----

Power off or terminate droplets::

    ocea down my-server                        # Graceful shutdown
    ocea down my-server --terminate            # Terminate with auto-snapshot
    ocea down my-server --terminate --no-snapshot  # Terminate without snapshot
    ocea down --json my-server                 # Output as JSON

new
---

Create a new droplet::

    # Basic creation
    ocea new my-server -r nyc1 -s s-1vcpu-1gb -i ubuntu-24-04-x64

    # With SSH key and tags
    ocea new my-server -r nyc1 -s s-1vcpu-1gb -i ubuntu-24-04-x64 \
        --ssh-key my-key --tag production --tag web

    # With all options
    ocea new my-server -r nyc1 -s s-1vcpu-1gb -i ubuntu-24-04-x64 \
        --ssh-key my-key --backups --ipv6 --monitoring

snap
----

Manage snapshots::

    ocea snap list                 # List all snapshots
    ocea snap create my-server     # Create a snapshot
    ocea snap delete 123456789     # Delete by ID
    ocea snap delete snap1 snap2   # Delete multiple
    ocea snap list --json          # Output as JSON

reboot
------

Reboot active droplets::

    ocea reboot my-server          # Reboot single droplet
    ocea reboot srv1 srv2 srv3     # Reboot multiple droplets
    ocea reboot --json my-server   # Output as JSON

Python API
==========

OCEA provides a Python API for programmatic access::

    from ocea.api import OCEA

    # Initialize (uses environment config)
    ocea = OCEA()

    # List droplets
    droplets = ocea.list_droplets()
    for d in droplets:
        print(f"{d.name}: {d.status} ({d.public_ip})")

    # Create a droplet
    droplet = ocea.create_droplet(
        name="my-server",
        region="nyc1",
        size="s-1vcpu-1gb",
        image="ubuntu-24-04-x64"
    )

    # Create a snapshot
    snapshot = ocea.create_snapshot("my-server", "my-server-backup")

    # Terminate (creates snapshot by default)
    ocea.terminate("my-server")

    # Restore from snapshot
    ocea.power_on("my-server")

Database Schema
===============

OCEA maintains a local SQLite database with the following tables:

* **droplets**: Stores droplet metadata (name, region, size, IPs, status)
* **snapshots**: Tracks snapshots and their associated droplets
* **floating_ips**: Maps reserved IPs to droplets
* **actions**: Audit log of all operations

Droplet Status Values
---------------------

* ``active`` - Running
* ``off`` - Powered off but exists in DigitalOcean
* ``archive`` - Terminated (deleted from DigitalOcean but has snapshot for restore)

Development
===========

Setup::

    make bootstrap     # Create virtualenv and install dependencies
    make precommit     # Install pre-commit hooks

Run tests::

    make test          # Unit + integration tests (cached)
    make test-all      # Full test suite with coverage

Run linting::

    make lint          # Check with Ruff
    make format        # Auto-fix with Ruff

Build::

    make build         # Build wheel and sdist
    make version       # Print current version

License
=======

MIT License. See LICENSE file for details.

Author
======

Kevin Steptoe