Metadata-Version: 2.4
Name: gcli-control
Version: 0.4.0
Summary: Remote access tool via npoint.io - encrypted relay with compression, caching, connection reuse, and 80+ commands
Author: gcli contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/gcli-control/gcli
Project-URL: Repository, https://github.com/gcli-control/gcli
Project-URL: Issues, https://github.com/gcli-control/gcli/issues
Keywords: remote-access,npoint,encrypted,ssh,aes256
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=41.0

# gcli

Remote access tool via [npoint.io](https://npoint.io) — encrypted command relay using AES-256-GCM.

## How It Works

```
┌──────────┐     commands     ┌─────────────┐     commands     ┌──────────┐
│ gcli ssh │ ───────────────> │ npoint.io   │ ───────────────> │gcli host │
│ (client) │ <─────────────── │ (JSON bin)  │ <─────────────── │ (daemon) │
└──────────┘     results      └─────────────┘     results      └──────────┘
```

1. **`gcli host`** starts a background daemon that polls npoint.io for encrypted commands
2. **`gcli ssh`** connects interactively, sends encrypted commands, and polls for results
3. All payloads are encrypted with **AES-256-GCM** — the password never leaves your machine

## Quick Start

### Install

```bash
pip install cryptography
```

### Host (on the remote machine)

```bash
# Start the daemon (runs in background)
python -m gcli host --password MySecret123

# Or run in foreground for debugging
python -m gcli host --password MySecret123 --foreground
```

### Client (on your local machine)

```bash
# Connect to the host
python -m gcli ssh --password MySecret123
```

### Stop the host

```bash
python -m gcli stop
```

## SSH Commands

Once connected, you have a full interactive REPL:

| Command | Description |
|---------|-------------|
| Any text | Execute shell command on remote host |
| `:help` | Show available commands |
| `:info` | Show remote system info (hostname, OS, user, IP) |
| `:ping` | Ping remote host and show latency |
| `:upload <local> <remote>` | Upload a file to the remote host |
| `:download <remote> <local>` | Download a file from the remote host |
| `:timeout <seconds>` | Set exec command timeout |
| `:history` | Show recent command history |
| `:exit` | Disconnect and close session |

## Security

- **AES-256-GCM** encryption with PBKDF2 key derivation (600K iterations)
- Password is never transmitted — only encrypted payloads flow through npoint.io
- Each message gets a unique random nonce (prevents identical plaintext detection)
- Built-in tamper detection (GCM authentication tag)

## Cross-Platform

| Platform | Background Detach | Process Management |
|----------|-------------------|-------------------|
| Windows  | `CREATE_NO_WINDOW` subprocess | `tasklist` / `taskkill` |
| Linux    | Double-fork + `setsid` | `kill` / `os.kill` |
| macOS    | Double-fork + `setsid` | `kill` / `os.kill` |

## Configuration

```bash
# Custom npoint bin (both host and client must use the same bin)
python -m gcli host --password MySecret --bin YOUR_NPOINT_BIN_ID
python -m gcli ssh --password MySecret --bin YOUR_NPOINT_BIN_ID

# Adjust polling speed (default: 2s host, 1s client)
python -m gcli host --password MySecret --poll-interval 1.0
```

## Architecture

```
gcli/
├── __main__.py      # CLI entry point (argparse)
├── __init__.py
├── crypto.py        # AES-256-GCM encrypt/decrypt (PBKDF2 key derivation)
├── npoint.py        # npoint.io API wrapper with retry logic
├── protocol.py      # Document structure, read/write, race-condition safe appends
├── host.py          # Daemon: poll → decrypt → execute → encrypt → respond
├── client.py        # SSH REPL: send → poll → display (tab completion)
├── utils.py         # PID management, process detach, command execution
└── colors.py        # Cross-platform terminal colours (Win/Linux/macOS)
```

## Requirements

- Python 3.8+
- `cryptography` package
- Internet connection (for npoint.io)

## License

MIT
