# ams-cli

**Repository Path**: rory-pd-yang/ams-cli

## Basic Information

- **Project Name**: ams-cli
- **Description**: ams-cli: cli for ams 
- **Primary Language**: Unknown
- **License**: Artistic-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ams-cli 🚀

`ams-cli` is a secure, local command execution runner designed for the AMS application. It acts as an execution bridge, safely running whitelisted actions generated by Large Language Models (LLMs) to query or control the local AMS application workspace.

---

## Key Features

- 🔒 **Security-First Sandboxing**: Strictly validates path operations against the configured `ams_app_dir` to block directory traversal attacks (e.g., `../../etc/passwd`).
- 🛡️ **Whitelisted Executions**: Subprocess executions via `safe_exec` are restricted to a whitelist of binaries (`make`, `python`, `python3`, `npm`, `pip`, `pip3`, `yarn`, `git`) and always run with `shell=False`.
- ⚠️ **Interactive Security Approvals**: Dangerous mutating operations (like writing/deleting files or restarting system services) prompt for human confirmation on `sys.stderr` when in a TTY session. Non-interactive sessions are blocked unless bypassed via `--yes` or `AMS_AUTO_APPROVE=true`.
- 📝 **Append-Only Audit Logs**: Every executed action, parameters (with credentials like `ams_app_token` automatically masked), execution duration, and success/approval status are logged in JSON Lines format to `~/.config/ams/audit.log`.
- 🔍 **Upfront Risk Validation**: The `validate` command pre-scans single commands or batch JSON files to report risk levels (`Safe`, `Medium`, `High`) and recommend safer alternatives before execution.
- 🧩 **Function-Calling Tool Manifest**: The `tools` command exports an `ams.tools.v2` manifest and OpenAI/Gemini-compatible function definitions from the same action registry.
- 🚦 **Typed Error Contracts & Policy Rules**: Validation and execution include stable error codes such as `ACTION_NOT_WHITELISTED`, `ARGUMENT_POLICY_DENIED`, and `NETWORK_POLICY_DENIED`, plus default argument-level policy blocks for `.env`, recursive deletes, and cloud metadata IP access.
- 💬 **Interactive Multi-Provider AI Chat**: The `chat` subcommand starts a terminal chat session with OpenAI (`gpt-4o`) or Google Gemini (`gemini-2.5-flash`) with real-time live Markdown streaming.
- ⚙️ **Automatic Environment Loading**: Supports loading configuration from environment variables, including `.env` files in both the current working directory (CWD) and project root directory.

---

## Installation

1. Navigate to the repository:
   ```bash
   cd ams-cli
   ```

2. Create the virtual environment and install dependencies:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip
   pip install -e .
   ```

3. Run the CLI using the convenient wrapper script:
   ```bash
   ./ams.sh --help
   ```

---

## Configuration

Configure `ams-cli` by running:
```bash
./ams.sh config --app-url "http://127.0.0.1:9000" --app-dir "/Users/rory/project/ams-cli"
```

### Auto-Loading Environment Variables
Alternatively, define settings in a `.env` file in the current working directory or project root:
```env
# .env
AMS_APP_URL="http://127.0.0.1:9000"
AMS_APP_DIR="/Users/rory/project/ams-cli"
AMS_ALLOWED_ACTIONS="status,sys_info,check_port,list_dir,create_dir,read_file,write_file,remove_file,copy_file,move_file,find_files,grep_text,replace_in_file,update_json_file,list_users,manage_user,logs,restart,deploy,http_ping,http_request,git_cmd,safe_exec,docker_ps,docker_logs,docker_restart,db_status,db_backup,systemd_status,systemd_restart,pm2_status,pm2_restart,dns_resolve,traceroute,create_word,create_ppt,create_pdf,create_excel"
```

To view active configurations:
```bash
./ams.sh config --show
```

---

## Usage Guide

### 1. List Available Actions & Risk Levels
Discover registered actions:
```bash
./ams.sh list
```
For machine-readable JSON including risk classifications and alternatives:
```bash
./ams.sh list --json
```

For LLM/function-calling clients, prefer the versioned tool manifest:
```bash
./ams.sh tools --format ams2 --json
./ams.sh tools --format openai --json
./ams.sh tools --format gemini --json
```

By default, `ams tools` only exposes actions currently allowed by `ams_allowed_actions`. Use `--include-blocked` to export the complete catalog with `in_whitelist=false` on blocked actions.

### 2. Pre-scan & Validate Risks
Audits planned actions for security risks before execution:
```bash
./ams.sh validate write_file file_path=config.json
```
For a batch JSON file:
```bash
./ams.sh validate --file batch.json --json
```

Validation reports include `risk_level`, `in_whitelist`, `approval_required`, `decision`, and a typed `error` object when blocked:
```json
{
  "code": "ARGUMENT_POLICY_DENIED",
  "message": "Writing or mutating .env files is denied by the default AMS policy.",
  "category": "policy",
  "recoverable": true,
  "hint": "Change the requested parameters or update ~/.config/ams/policy.json if this is an approved enterprise exception.",
  "details": {
    "rule_id": "deny-env-file-mutation",
    "action": "write_file"
  }
}
```

### 3. Run a Single Action
Run a registered action:
```bash
./ams.sh run logs lines=3
```
Bypass approval prompt for dangerous actions:
```bash
./ams.sh run remove_file file_path=old.txt --yes
```

### 4. Run Batch Commands
Execute a series of actions sequentially:
```bash
echo '[{"action": "status"}, {"action": "logs", "params": {"lines": 2}}]' | ./ams.sh batch
```

### 5. MCP & Function Calling Integration
Start the MCP stdio server:
```bash
./ams.sh mcp
```

The MCP `tools/list` response reuses the `ams.tools.v2` manifest source, so MCP clients and direct function-calling clients see the same input schemas and whitelist state.

Recommended agent flow:
```text
1. Discover tools: ams tools --format openai --json
2. Let the model produce a tool call with JSON arguments.
3. Preflight: ams validate <action> --params '<json>' --json
4. Execute only when decision is Allowed, or after your human approval flow.
5. Run: ams run <action> --params '<json>' --json
```

Execution responses keep `error` as a legacy string for old clients and add `error_object` for stable machine handling:
```json
{
  "success": false,
  "error": "Security violation: Action 'deploy' is not in the allowed_actions whitelist.",
  "error_object": {
    "code": "ACTION_NOT_WHITELISTED",
    "category": "policy"
  }
}
```

### 6. Execution-Only Plans
`ams-cli` supports backend-created execution plans without requiring an embedded LLM planner.

```json
{
  "schema_version": "ams.plan.v1",
  "name": "diagnostics",
  "steps": [
    {"id": "status", "action": "status", "params": {}},
    {"id": "sys", "action": "sys_info", "params": {}, "depends_on": ["status"]}
  ]
}
```

Validate before execution:

```bash
./ams.sh plan validate plan.json --json
```

Run after validation and approval:

```bash
./ams.sh plan run plan.json --json --yes
```

Runtime worker mode:

```bash
./ams.sh plan run plan.json \
  --json \
  --yes \
  --run-id run_from_ams_backend_001 \
  --correlation-id request_001 \
  --events-jsonl ./ams-events.jsonl
```

Dry-run before execution:

```bash
./ams.sh plan run plan.json --json --dry-run
```

The result envelope uses `ams.run.v1`; event streams use `ams.event.v1`. Java backend should treat `run_id`, `correlation_id`, `status`, `steps[*].status`, and `steps[*].error.code` as stable machine-readable fields.

Recommended Java backend flow:

```text
1. LLM or planner creates ams.plan.v1.
2. Backend persists the plan and creates run_id/correlation_id.
3. Backend calls: ams plan run plan.json --json --events-jsonl events.jsonl.
4. Backend tails or reads JSONL events for progress.
5. Backend stores final ams.run.v1 response.
6. Backend maps typed errors to retry, approval, or user-facing remediation.
```

Plan execution is intentionally not natural-language planning. AMS backend or another agent runtime owns planning; `ams-cli` owns local validation, policy, execution, and audit.

### 7. Start Interactive AI Chat Mode
Interactive session with real-time streaming:
```bash
./ams.sh chat --provider google
```

---

## Package Release Automation

To compile and upload the library to TestPyPI or production PyPI, use the release automation script:
```bash
./release.sh
```

---

## Testing

Run the automated test suite with coverage:
```bash
pytest --cov=ams
```