Metadata-Version: 2.5
Name: warg-shell
Version: 1.2.0
Summary: DigitalOcean Warg - SSH-like connection to DigitalOcean PaaS console
Project-URL: Homepage, https://github.com/Starkstonks/warg-shell
Project-URL: Issues, https://github.com/Starkstonks/warg-shell/issues
Author-email: Rémy Sanchez <remy.sanchez@hyperthese.net>
License-Expression: WTFPL
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Shells
Requires-Python: >=3.11
Requires-Dist: click
Requires-Dist: httpx
Requires-Dist: keyring
Requires-Dist: psutil
Requires-Dist: rich
Requires-Dist: rich-click
Requires-Dist: websockets
Description-Content-Type: text/markdown

# DigitalOcean Warg

This project allows you to take control of a DigitalOcean PaaS terminal from
your real terminal, making the experience a lot better than just using an
emulator from the JS side.

There is an authentication protocol to be documented.

## Usage

First, you need to authenticate against your Warg server. Do:

```bash
uvx warg-shell auth <your-domain> <your-token>
```

Then you can use any component that you want:

```bash
uvx warg-shell shell <your-domain> <your-product> <your-env> <your-component>
```

You can also download a dump of a database:

```bash
uvx warg-shell pg-dump <your-domain> <your-product> <your-env> <your-db> -o dump.sql
```

## Where is the token stored?

The auth token goes through [keyring](https://pypi.org/project/keyring/), so
it ends up in your platform's credential store: Secret Service / KWallet on
Linux, Keychain on macOS, Credential Manager on Windows.

Under **WSL** there is usually no credential store, so `warg-shell` ships a
small backend that stores the token in the **Windows** Credential Manager
through `powershell.exe`. Nothing to install or configure, as long as WSL
interop is enabled (it is by default).

## Development

The project is managed with [uv](https://docs.astral.sh/uv/) and requires
Python 3.11 or later.

```bash
uv sync            # create the venv and install everything
make clean         # ruff format + ruff check --fix
make test          # pytest
uv build           # build the sdist and the wheel into dist/
```

### Releasing

Releases are published to PyPI by the `Release` GitHub workflow through
[trusted publishing](https://docs.pypi.org/trusted-publishers/) — no API token
is involved. To cut a release:

1. Bump the version in `pyproject.toml` (`uv version 1.2.0`) and merge to
   `master` following git-flow.
2. Tag the merge commit with the bare version (`git tag 1.2.0`) and push the
   tag. The workflow runs the CI, checks that the tag matches the project
   version, builds the sdist and wheel, and uploads them.

The workflow publishes from the `pypi` GitHub environment, which is what the
trusted publisher is registered against on PyPI.
