# gd-cli

**Repository Path**: lauset/gd-cli

## Basic Information

- **Project Name**: gd-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gd-cli

CLI tool for communicating with Godot GDExtension RemoteServer via TCP.

## Quick Start

### Build

```bash
cargo build --release
```

Binary: `target/release/gd-cli`

### Install Locally

```bash
# Install to ~/.cargo/bin
cargo install --path .

# Or copy binary manually
cp target/release/gd-cli /usr/local/bin/
```

After installation, `gd-cli` is available globally:

```bash
gd-cli version
```

### Run Tests

```bash
# Run unit tests (no server required)
cargo test --lib

# Run integration tests (requires gdext server running)
cargo test --lib -- --ignored

# Run all tests including ignored
cargo test --lib -- --include-ignored

# Run with verbose output
cargo test --lib -- --nocapture
```

## Usage

```bash
gd-cli [-H HOST] [-p PORT] <command> [args...]
```

### Options

| Flag         | Description       | Default     |
|--------------|-------------------|-------------|
| `-H, --host` | TCP server host   | `127.0.0.1` |
| `-p, --port` | TCP server port   | `9527`      |

Priority: CLI args > `.env` file > hardcoded defaults.

### Commands

#### version

```bash
gd-cli version
# → 0.1.5 (da8cf32, SHA: ...)
```

#### emit — Trigger message bus signal

Signal types: `interacted` / `view_controlled` / `object_controlled` / `data_received` / `custom_event`

```bash
gd-cli emit <signal_type> [data]
gd-cli emit interacted 'true'
gd-cli emit custom_event '{"msg":"hello"}'
```

#### ds — DataStore global data

```bash
gd-cli ds set <key> <value>    # Set data (auto flush)
gd-cli ds get <key>            # Get data
gd-cli ds keys                 # List all keys
gd-cli ds remove <key>         # Remove data
gd-cli ds clear                # Clear all data
```

Example:

```bash
gd-cli ds set player_name "大华"
# → ok

gd-cli ds get player_name
# → 大华

gd-cli ds keys
# → ["player_name"]
```

#### config — RsInit persistent config

```bash
gd-cli config                  # Read all config
gd-cli config <classify>       # Read by classify (e.g. app, device)
```

#### sys — System information

```bash
gd-cli sys platform <name>     # Check platform: windows / macos / linux / web
gd-cli sys build <type>        # Check build: editor / debug / release
gd-cli sys time                # Get runtime duration (seconds)
```

#### cache — RsRef global cache

```bash
gd-cli cache get <key>         # Get cache
gd-cli cache set <key> <value> # Set cache
```

## Configuration

Place a `.env` file in the same directory as the binary:

```env
GD_SERVER_HOST=127.0.0.1
GD_SERVER_PORT=9527
```

The CLI resolves settings in this order:

1. CLI arguments (`-H`, `-p`)
2. Environment variables (`GD_SERVER_HOST`, `GD_SERVER_PORT`)
3. `.env` file (same directory as binary)
4. Hardcoded defaults (`127.0.0.1:9527`)

## Protocol

TCP, JSON Lines protocol (one JSON per line, separated by newline).

Request:

```json
{"id": 1, "method": "ds_set", "args": ["key", "val"]}
```

Response:

```json
{"id": 1, "result": "ok", "error": null}
```

## Library Usage

```rust
use gd_cli::{Cli, load_env, execute_command};
use clap::Parser;

fn main() {
    load_env();
    let cli = Cli::parse();
    match execute_command(&cli) {
        Ok(result) => println!("{}", result),
        Err(e) => eprintln!("Error: {}", e),
    }
}
```

## Project Structure

```text
gd-cli/
├── src/
│   ├── main.rs      # Binary entry point
│   ├── lib.rs       # Library: protocol, TCP, command execution
│   └── cli.rs       # CLI argument definitions (clap)
├── skills/
│   ├── gd-cli/
│   │   ├── SKILL.md # Agent skill instructions
│   │   └── scripts/ # Packaged binary
│   └── references/  # Protocol documentation (split)
├── .agent/
│   └── skills/
│       └── SKILL.md # Build/upgrade skill
├── .env             # Default server configuration
├── Cargo.toml
└── README.md
```

## Requirements

- Rust 1.95+ (edition 2024)
- Godot GDExtension with RemoteServer running