# AIANDME (BETA) - AI Agent Security Testing CLI

## NAME

**aiandme** - command-line interface for AI agent security testing

## SYNOPSIS

```
aiandme [--base-url URL] COMMAND [OPTIONS] [ARGS]
```

## DESCRIPTION

AIandMe CLI provides security testing for AI chatbots and agents. Run adversarial tests, behavioral analysis, and export guardrails configurations.

## GETTING STARTED

```bash
# 1. Install
pip install aiandme-cli

# 2. Authenticate (opens browser)
aiandme login

# 3. Select organisation
aiandme orgs list
aiandme switch <org-id>

# 4. Configure a model provider
aiandme providers add --name openai --api-key sk-...

# 5. Create a project from system prompt
aiandme init --name "My Bot" --prompt ./system_prompt.txt

# 6. Run security tests
aiandme test \
  --chat-endpoint https://my-bot.com/chat \
  --chat-header "Authorization: Bearer token"

# 7. Check status and results
aiandme status
aiandme logs
```

---

## COMMANDS

### Authentication

| Command | Description |
|---------|-------------|
| `login` | Authenticate via browser (OAuth PKCE) |
| `logout` | Clear stored credentials |
| `whoami` | Show current authentication status |

### Organisation Management

| Command | Description |
|---------|-------------|
| `orgs list` | List available organisations |
| `orgs current` | Show current organisation |
| `switch <id>` | Switch to organisation |

### Provider Management

Providers are LLM configurations used for running security tests.

| Command | Description |
|---------|-------------|
| `providers list` | List configured providers |
| `providers add` | Add new provider |
| `providers update <id>` | Update provider config |
| `providers remove <id>` | Remove provider |

**providers add** options:
```
--name, -n        Provider name: openai, claude, azureopenai, gemini, grok, custom
--api-key, -k     API key
--endpoint, -e    Endpoint URL (required for azureopenai, custom)
--model, -m       Model name (optional)
--default         Set as default provider
--interactive     Interactive configuration mode
```

### Project Management

| Command | Description |
|---------|-------------|
| `projects list` | List projects |
| `projects use <id>` | Select project |
| `projects current` | Show current project |
| `projects show [id]` | Show project details |

**init** - Create project from various sources:
```
aiandme init --name NAME [OPTIONS]

--prompt PATH       Extract scope from system prompt file
--endpoint URL      Probe live chatbot endpoint
--repo PATH         Scan repository for prompts/tools
--openapi PATH      Parse OpenAPI specification
--description       Project description
--yes, -y           Skip confirmation prompts
```

### Test Execution

**test** - Run security tests on current project:
```
aiandme test [OPTIONS]

Test Category:
  --test-category, -t   Test to run (default: owasp_multi_turn)
                        Values: owasp_single_turn, owasp_multi_turn,
                                owasp_agentic_multi_turn, owasp_adaptive,
                                behavioral

Testing Level:
  --testing-level, -l   Depth of testing (default: unit)
                        unit (~20 min), system (~45 min), acceptance (~90 min)

Chat Endpoint (required):
  --chat-endpoint       Chat completion URL of the bot to test
  --chat-header         Header for chat endpoint (repeatable)
  --chat-payload        JSON payload template for chat

Init Endpoint (optional):
  --init-endpoint       Thread initialization URL
  --init-header         Header for init endpoint (repeatable)
  --init-payload        JSON payload for init

Auth Endpoint (optional):
  --auth-endpoint       Auth/token endpoint URL
  --auth-header         Header for auth endpoint (repeatable)
  --auth-payload        JSON payload for auth

Other:
  --provider-id         Provider to use (default: first available)
  --name, -n            Experiment name (auto-generated if omitted)
  --lang                Language (default: english). Accepts codes: en, de, es...
  --streaming           Enable streaming mode (requires wss:// endpoint)
  --no-auto-start       Create without starting (manual mode)
  --wait, -w            Wait for completion
  --fail-on SEVERITY    Exit non-zero if findings >= severity
                        Values: critical, high, medium, low, any
```

### Experiment Management

| Command | Description |
|---------|-------------|
| `experiments list` | List experiments |
| `experiments show <id>` | Show experiment details |
| `experiments status <id>` | Check status |
| `experiments status <id> --watch` | Watch until completion |
| `experiments wait <id>` | Wait with progressive backoff |
| `experiments logs <id>` | List experiment logs |
| `experiments report <id>` | Download HTML report |

**experiments wait** options:
```
--timeout MINUTES     Max wait time (default: 120)
```
Progressive backoff: 30s → 60s → 120s → 300s

**status** (top-level alias):
```
aiandme status [experiment_id] [--watch]
```
Without ID, shows most recent experiment.

### Results & Export

**logs** - View experiment results:
```
aiandme logs [experiment_id] [OPTIONS]

--format          Output format: table, json, csv (default: table)
--verdict         Filter by verdict: pass, fail
--page            Page number
--size            Items per page
```

**posture** - Security posture score:
```
aiandme posture [--json]
```

**guardrails** - Export guardrails configuration:
```
aiandme guardrails [OPTIONS]

--vendor          Target vendor: aiandme, openai, azure, bedrock
--format          Output format: json, yaml (default: json)
--output, -o      Output file path
```

### Documentation

```
aiandme docs [TOPIC]
```
Opens documentation in browser. Topics: quickstart, api, cli, concepts, testing.

---

## CONFIGURATION

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AIANDME_BASE_URL` | API base URL | https://api.aiandme.io |
| `AIANDME_AUTH0_DOMAIN` | Auth0 domain (on-prem) | aiandme.eu.auth0.com |
| `AIANDME_AUTH0_CLIENT_ID` | Auth0 client ID (on-prem) | - |

### On-premises

```bash
export AIANDME_BASE_URL=https://api.your-domain.com
aiandme login
```

---

## FILES

| Path | Description |
|------|-------------|
| `~/.aiandme/` | Configuration directory |
| `~/.aiandme/credentials.json` | Auth tokens (mode 600) |

---

## EXIT STATUS

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error or test failure (with `--fail-on`) |

---

## EXAMPLES

### Basic workflow
```bash
aiandme login
aiandme switch abc123
aiandme projects use def456
aiandme test --chat-endpoint https://bot.com/chat
aiandme status --watch
aiandme logs
```

### CI/CD integration
```bash
aiandme test \
  --chat-endpoint $BOT_ENDPOINT \
  --chat-header "Authorization: Bearer $BOT_TOKEN" \
  --testing-level system \
  --wait \
  --fail-on high
```

### Multi-endpoint bot with auth
```bash
aiandme test \
  --auth-endpoint https://bot.com/oauth/token \
  --auth-payload '{"client_id":"x","client_secret":"y"}' \
  --init-endpoint https://bot.com/threads \
  --init-header "Content-Type: application/json" \
  --chat-endpoint https://bot.com/chat \
  --chat-header "Content-Type: application/json" \
  --chat-payload '{"messages":[{"role":"user","content":"$PROMPT"}]}'
```

### Export guardrails for OpenAI
```bash
aiandme guardrails --vendor openai --format json -o guardrails.json
```

### Create project from repository
```bash
aiandme init \
  --name "Support Bot" \
  --repo ./my-agent \
  --prompt ./prompts/system.txt
```

---

## SEE ALSO

- Documentation: https://docs.aiandme.io
- API Reference: https://docs.aiandme.io/api
- GitHub: https://github.com/aiandme/cli
