Metadata-Version: 2.4
Name: assh-toolkit
Version: 0.1.0
Summary: Agentic SSH toolkit for stateful, token-efficient infrastructure workflows.
Author: Codex
License: MIT
Requires-Python: >=3.11
Requires-Dist: pydantic-settings<3.0.0,>=2.13.1
Requires-Dist: pydantic<3.0.0,>=2.12.5
Requires-Dist: pyyaml<7.0.0,>=6.0.3
Requires-Dist: rich<15.0.0,>=14.3.3
Requires-Dist: typer<0.25.0,>=0.24.1
Description-Content-Type: text/markdown

# assh

`assh` is an agentic SSH toolkit for stateful, token-efficient remote execution.

`assh` provides a typed Python package and CLI for:

- repo and global target resolution
- stateful remote execution with output shaping
- environment-set injection
- reusable workflow scripts
- Docker and Kubernetes helpers
- SSH-driven remote worker deployment and task lifecycle management

## Status

`v0.1.0` is the first MVP release.

The current release includes:

- async-first SSH transport with persisted remote working directory state
- JSON, XML, and Rich output from a shared canonical result model
- repo-local and global SQLite-backed target and env-set state
- `push` and `fetch` helpers for remote file transfer
- deployable remote worker support for long-running task lifecycle control
- automated scenario coverage derived from Astra and Nexus workflows
- a guarded real-VM validation suite exercised against `root@192.237.244.107`

## Install

### Local development

```bash
uv sync --group dev
uv run assh --help
```

### Install as a tool

```bash
uv tool install --from . assh
```

## Quick start

```bash
uv run assh init
uv run assh target add vm root@192.237.244.107
uv run assh run "uname -a && whoami && pwd" --target vm
```

Persist a remote workspace across commands:

```bash
uv run assh chain \
  --target vm \
  --step "mkdir -p /tmp/assh-demo" \
  --step "cd /tmp/assh-demo" \
  --step "printf 'hello from assh\n' > note.txt"

uv run assh run "pwd && cat note.txt" --target vm
```

Use env sets with automatic redaction:

```bash
uv run assh env set deploy APP_ENV production
uv run assh env set deploy API_TOKEN super-secret-token
uv run assh env enable deploy
uv run assh run "printf 'APP_ENV=%s\nTOKEN=%s\n' \"\$APP_ENV\" \"\$API_TOKEN\"" --target vm
```

Use the remote worker for long-running tasks:

```bash
uv run assh worker deploy --target vm
uv run assh task start "printf 'start\n'; sleep 10; printf 'done\n'" --target vm
uv run assh task list --target vm
uv run assh task logs <task-id> --target vm
```

## Validation

Core local checks:

```bash
uv run ruff check .
uv run mypy src
uv run pytest
uv build
```

Guarded real-VM validation:

```bash
ASSH_E2E_ENABLE=1 \
ASSH_E2E_TARGET=root@192.237.244.107 \
ASSH_E2E_WORKDIR=/tmp/assh-scenarios \
ASSH_E2E_STRICT_HOSTKEY=accept-new \
uv run pytest -m e2e tests/e2e/test_vm_manual.py -vv
```

## Documentation

- [AGENTS.md](AGENTS.md) is the tracked repo entrypoint.
- [docs/](docs/) contains the public Mintlify docs.
- [docs/examples.mdx](docs/examples.mdx) contains copy-paste usage examples.

## Release workflow

- `.github/workflows/ci.yml` runs lint, typecheck, tests, and package builds on pushes and pull requests.
- `.github/workflows/release.yml` verifies the tagged revision before publishing to PyPI.
