contree-cli 0.2.3__py3-none-any.whl

contree_cli-0.2.3.dist-info/METADATA

@@ -0,0 +1,323 @@
+Metadata-Version: 2.3
+Name: contree-cli
+Version: 0.2.3
+Summary: ConTree simple CLI
+Requires-Python: >=3.10
+Project-URL: Homepage, https://contree.dev
+Project-URL: Documentation, https://docs.contree.dev/cli/
+Project-URL: Repository, https://github.com/nebius/contree-cli
+Project-URL: Issues, https://github.com/nebius/contree-cli/issues
+Project-URL: Changelog, https://github.com/nebius/contree-cli/releases
+Description-Content-Type: text/markdown
+
+# contree-cli
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#zero-dependencies)
+[![PyPI](https://img.shields.io/pypi/v/contree-cli.svg)](https://pypi.org/project/contree-cli/)
+
+Command-line client for the [ConTree](https://contree.dev) sandboxing platform — secure, VM-isolated sandboxes with git-like branching for AI agents and developers.
+
+```bash
+eval $(contree use tag:ubuntu:latest)   # pick a base image for current session
+contree run apt-get update -qq          # each run snapshots the result
+contree run apt-get install -y curl     # builds on the previous snapshot
+contree session branch experiment       # branch the sandbox state
+contree run -- make test                # experiment freely
+contree session checkout main           # switch back instantly
+contree session rollback 2              # or rewind two steps
+```
+
+## What is ConTree?
+
+[ConTree](https://contree.dev) is a secure sandbox API that runs every command inside a VM-isolated instance and snapshots the full filesystem after each execution. These snapshots (called **images**) form a tree — branch from any checkpoint, explore paths in parallel, and roll back on failure.
+
+**Built for AI agents that think ahead:**
+
+- **Tree-search execution** — branch sandbox state so an agent can explore multiple solution paths in parallel and keep the best one
+- **Instant rollback** — backtrack to any previous checkpoint without rebuilding from scratch
+- **Safe code execution** — run untrusted or LLM-generated code inside VM-level isolation; crashes and side effects stay in the sandbox
+- **Session continuity** — rewind and resume long-running agent workflows with full filesystem context preserved
+
+`contree-cli` talks to the ConTree API. Install it, authenticate with your project token, and create sandboxes, run commands, inspect filesystems, and manage sessions — all from your terminal, shell scripts, or agent toolchains.
+
+## Install
+
+```bash
+pip install contree-cli
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install contree-cli
+```
+
+<details>
+<summary>More options (pipx, from source)</summary>
+
+```bash
+# pipx
+pipx install contree-cli
+
+# From source
+git clone https://github.com/nebius/contree-cli.git
+cd contree-cli
+pip install .
+```
+
+</details>
+
+Verify:
+
+```bash
+contree --help
+```
+
+**Requirements:** Python 3.10+ and nothing else. Zero external dependencies — stdlib only.
+
+## Quick Start
+
+### 1. Authenticate
+
+```bash
+contree auth
+```
+
+You'll be prompted to enter your API token securely. The CLI verifies it and saves it to `~/.config/contree-cli/config.ini`.
+
+### 2. Start a session
+
+```bash
+eval $(contree use tag:ubuntu:latest)
+```
+
+This picks a base image and creates a session. The `eval` wrapper exports the session variable so subsequent commands share the same state.
+
+### 3. Run commands
+
+```bash
+contree run uname -a                  # direct execution
+contree run apt-get install -y curl   # installs persist to next run
+contree run -s -- 'echo $PATH'        # shell mode for expansions
+```
+
+Each non-disposable `run` produces a new image — a full filesystem checkpoint.
+
+### 4. Inspect without spawning
+
+```bash
+contree ls /usr/bin          # list files (no VM needed)
+contree cat /etc/os-release  # read files (no VM needed)
+contree cp /app/output.log . # download to local machine
+```
+
+### 5. Branch and roll back
+
+```bash
+contree session branch experiment     # create a branch
+contree run -- make test              # experiment on it
+contree session checkout main         # switch back
+contree session rollback 1            # undo last run
+```
+
+## Interactive Shell
+
+`contree shell` starts a REPL where bare commands run in the sandbox automatically:
+
+```
+$ contree shell
+contree:/> apt-get update -qq
+...
+contree:/> apt-get install -y curl
+...
+contree:/> curl -sI https://example.com
+HTTP/2 200
+...
+contree:/> cd /etc
+contree:/etc> cat os-release
+PRETTY_NAME="Ubuntu 24.04 LTS"
+...
+contree:/etc> contree session branch experiment
+Created branch 'experiment'
+contree:/etc> exit
+```
+
+The shell provides tab completion for commands, paths, image tags, and operation IDs. `ls` and `cat` map to the fast API inspection commands by default. `vim`/`vi`/`nano` open `contree file edit` with your local `$EDITOR`.
+
+## Commands
+
+| Command | Aliases | Description |
+|---|---|---|
+| `use IMAGE` | `ci` | Set or show current session image |
+| `run [-- CMD]` | | Spawn a sandbox instance, execute command |
+| `images [--prefix]` | `img` | List available images |
+| `tag UUID TAG` | | Tag or untag an image |
+| `ps` | | List operations (instances, imports) |
+| `kill UUID` | | Cancel an operation (`--all` for all) |
+| `show UUID` | | Show operation result |
+| `ls [PATH]` | | List files in session image (no VM) |
+| `cat PATH` | | Show file content from session image (no VM) |
+| `cp PATH DEST` | | Download file from image to local path |
+| `file edit PATH` | `e` | Edit remote file via local `$EDITOR` |
+| `file cp SRC DEST` | | Upload local file into session image |
+| `cd [PATH]` | | Change working directory in session |
+| `session` | `s` | Show current session info |
+| `session list` | `ls` | List all sessions |
+| `session branch` | `br` | Create or list branches |
+| `session checkout` | `co` | Switch active branch |
+| `session rollback [N]` | `rb` | Revert N steps in history |
+| `session show` | | Display session history DAG |
+| `auth` | | Configure authentication (secure prompt) |
+| `auth profiles` | | List saved profiles |
+| `auth switch NAME` | | Switch active profile |
+| `shell` | | Start interactive REPL |
+
+See the full [command reference](https://docs.contree.dev/cli/commands/) for all flags and options.
+
+## Execution Modes
+
+The `run` command supports four execution modes:
+
+```bash
+# Direct — arguments are the command
+contree run uname -a
+
+# Shell — arguments joined, passed to sh -c
+contree run -s -- 'echo $HOME && ls /'
+
+# Interpreter — local script executed remotely
+contree run -I ./deploy.sh
+
+# Piped stdin — stdin forwarded to the command
+echo 'SELECT 1' | contree run -- psql
+```
+
+### File injection
+
+Mount local files into the sandbox:
+
+```bash
+contree run --file ./app.py:/app/app.py -- python /app/app.py
+contree run --file ./config.yaml --file ./data.csv -- ./process.sh
+```
+
+File specs support permissions: `host_path[:remote_path][:uUID][:gGID][:mMODE]`
+
+### Shebang scripts
+
+```bash
+#!/usr/bin/env -S contree run -I
+apt-get update -qq
+apt-get install -y curl
+curl https://example.com
+```
+
+Save as `setup.sh`, `chmod +x`, and run it directly.
+
+## Sessions and Branching
+
+Sessions track your sandbox state with git-like branching and history:
+
+```
+main:  A ── B ── C ── D
+                  \
+experiment:        E ── F
+```
+
+Every `run` creates a checkpoint. Branch to explore alternatives. Roll back to any point. Switch branches instantly.
+
+```bash
+contree session                       # show current state
+contree session show                  # display history DAG
+contree session branch feature        # create branch from HEAD
+contree session checkout feature      # switch to it
+contree session rollback 3            # go back 3 steps
+contree session use other-session     # import image from another session
+```
+
+## Output Formats
+
+All commands support structured output via `-f`/`--format`:
+
+```bash
+contree images -f json                # JSON (one object per line)
+contree images -f json-pretty         # pretty-printed JSON array
+contree ps -f csv                     # RFC 4180 CSV
+contree ps -f tsv                     # tab-separated values
+contree ls -f table                   # ASCII table
+```
+
+Pipe JSON output into `jq`, feed CSV into spreadsheets, or parse programmatically in your agent toolchain.
+
+## Configuration
+
+### Config file
+
+`~/.config/contree-cli/config.ini`:
+
+```ini
+[DEFAULT]
+profile = default
+
+[profile:default]
+token = eyJ...
+url = https://contree.dev
+```
+
+### Multiple profiles
+
+```bash
+contree auth --profile=staging        # save staging token
+contree auth --profile=prod           # save production token
+contree auth profiles                 # list all profiles
+contree auth switch staging           # switch active profile
+```
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `CONTREE_TOKEN` | API bearer token (overrides config) |
+| `CONTREE_URL` | API base URL (overrides config) |
+| `CONTREE_PROFILE` | Active profile name |
+| `CONTREE_SESSION` | Explicit session key (for multi-terminal workflows) |
+| `CONTREE_SESSION_DB` | Path to session SQLite database |
+
+Environment variables take precedence over the config file. `--token` and `--url` flags override everything.
+
+## Zero Dependencies
+
+`contree-cli` uses only the Python standard library. No `requests`, no `click`, no `rich` — just `http.client`, `argparse`, `json`, `sqlite3`, and friends. It runs anywhere Python 3.10+ is available with nothing to install beyond the package itself.
+
+## Development
+
+```bash
+git clone https://github.com/nebius/contree-cli.git
+cd contree-cli
+uv sync --group dev
+```
+
+```bash
+make lint       # ruff check --fix
+make types      # mypy strict mode
+make check      # lint + types
+make tests      # lint + types + pytest
+```
+
+The project enforces strict mypy, ruff linting (E/F/W/I/UP/B/SIM/RUF rules), and full test coverage across 23+ test modules.
+
+## Documentation
+
+Full documentation is available at **[docs.contree.dev/cli](https://docs.contree.dev/cli/)**, including:
+
+- [Tutorial](https://docs.contree.dev/cli/tutorial/) — step-by-step from installation to automation
+- [Command Reference](https://docs.contree.dev/cli/commands/) — every command, flag, and subcommand
+
+## Links
+
+- [ConTree Platform](https://contree.dev)
+- [Documentation](https://docs.contree.dev/cli/)
+- [PyPI](https://pypi.org/project/contree-cli/)
+- [Issues](https://github.com/nebius/contree-cli/issues)
+- [Releases](https://github.com/nebius/contree-cli/releases)

contree_cli-0.2.3.dist-info/RECORD

@@ -0,0 +1,35 @@
+contree_cli/__init__.py,sha256=kWY9HrMJZFOQCtp_sbnByckRnlfEn2yVBPQzPWbym5I,922
+contree_cli/__main__.py,sha256=3ATWrPD7wSrbV45h1lZSktTXdlxwIwgibwp2zVWoq90,1703
+contree_cli/arguments.py,sha256=qJfANiNbFOYjh3mNWDsX_v6AzLID7HVHqq-Tw3e_MIk,4380
+contree_cli/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+contree_cli/cli/auth.py,sha256=7hKmUZ-5UZzOJKXcmsfV8gou_-ybMRCntutFX0iKU5E,3617
+contree_cli/cli/cat.py,sha256=ItTREOPp4Cztl-IrHAFim9lvSQhKIal-_bEBWPExdbE,2154
+contree_cli/cli/cd.py,sha256=dVrvKD3IyRRVv_zv-tdnAM9fdQ5-IEHGzQsPeqigal4,1311
+contree_cli/cli/cp.py,sha256=EqS3SLGeSszqUOwdZN9vCuyA27TCdl7ImdJ8TQN5A8A,3335
+contree_cli/cli/file.py,sha256=edRj_7SAijvExZqTWqZlswBZ478TjlFyMVWlQDD_HNs,5589
+contree_cli/cli/images.py,sha256=vM57eKmWG4xGaAz9j6DRV8qdbw-Ufa9fBhZJhgrnScI,2627
+contree_cli/cli/kill.py,sha256=ZM7XFMPN6-A9BOyiwQngeheyH_WqNR_lqd-9RJJBXlk,2555
+contree_cli/cli/ls.py,sha256=M_P27Z102vZkq_vcfuU_lYa8Tfrk9Lh89WjAP9DK5EU,2493
+contree_cli/cli/ps.py,sha256=YjfdWf5LlSX1CrTNBDMsmRlwwy6WjpPsp-YCczLSMHg,3737
+contree_cli/cli/run.py,sha256=IGW9HU386_tRNS1jIsHKXLxoL2yJlj9QQ2AqUEpybLw,14849
+contree_cli/cli/session.py,sha256=xDGNOdhFQ21I5cM0VqNPqQonhCK2L0SWiB-0Mfec_k4,7845
+contree_cli/cli/show.py,sha256=ipQ5C2CEhuUKpBs5EG0EmML6WO2TOx-ecnJp8x7dnvg,2725
+contree_cli/cli/tag.py,sha256=rD_5p-0CeqL_43_RdBx51woE8i5ZpnZNvFYQxgUA7XM,1384
+contree_cli/cli/use.py,sha256=Rdppxho0RaggBSh2UwlhDfDJ-n5lq3wroEWaajstv6E,3401
+contree_cli/client.py,sha256=zlbDn9lRX1AWGHFvzj2rV6MIsQmBunzAIP7yR8c4DCk,6403
+contree_cli/config.py,sha256=8RGmVasZ2g5XF6ocRH24tE5eapd7C4jxwPekjAai6C8,3395
+contree_cli/log.py,sha256=M7t7CwYGMkAM7y4VZM5wWEewOjTaxShB3z7CEnjbC0E,1291
+contree_cli/mapped_file.py,sha256=qvXPD4r5LbrMD0VG0rWNc3gwFcA8vKKtbMKIaWcbNlA,3085
+contree_cli/output.py,sha256=nnksLliHaAIYTBm4bDoUIWlcBtYsVxKt8fMG6iHQQBo,10950
+contree_cli/session.py,sha256=dviGgQZgyqz3gDX6uRNAz3DZW8GaQDh4zgSg6FvoKSw,24503
+contree_cli/shell/__init__.py,sha256=HyMGi1KzNv7Z2wdGx3fnMOByp5oxGGzEVKzgtVYBoHY,1692
+contree_cli/shell/completer.py,sha256=4qg_PJdRPkWd9HYRvhuVYWW99IpLDGHosii0W-mWJt8,16653
+contree_cli/shell/history.py,sha256=OOQ-9cEI7q85X5PXLT_73crHRdBcFeCjLBtAe12yHbA,1468
+contree_cli/shell/parser.py,sha256=8yySuOk1ZnQbAPqSJTX5UA6W_L5Ks2a4bEkBzYqNWrA,3240
+contree_cli/shell/repl.py,sha256=lEfXptszY7fTn8cMkc805o9p4liyMD8tei9bLAqYmCY,17290
+contree_cli/shell/trie.py,sha256=ZY6vfWPQyI_hZKllhKfZ0vjW-tuX5X11hoRY-rXpa4w,3607
+contree_cli/types.py,sha256=NsalGbym37z7cgJWTsWsP51Cn35mjnFB2OSmjPvNFgc,2617
+contree_cli-0.2.3.dist-info/WHEEL,sha256=hbX8mDThv1n7VEIpQRy6c2yAFTw4iAQlEC53gDAhHSo,80
+contree_cli-0.2.3.dist-info/entry_points.txt,sha256=qlYk-p3Il1r2Yo9pghiZmxHT1SO9yccE5DAmymwNHeU,55
+contree_cli-0.2.3.dist-info/METADATA,sha256=HfRtFOuiDNRCBBlcNz72-yr5DgL2dUQzFY1fi385-Qs,10485
+contree_cli-0.2.3.dist-info/RECORD,,

contree_cli-0.2.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.6
+Root-Is-Purelib: true
+Tag: py3-none-any

contree_cli-0.2.3.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+contree = contree_cli.__main__:main
+