|
| 1 | +--- |
| 2 | +title: "CLI Reference" |
| 3 | +description: "MeshGuard command-line interface reference" |
| 4 | +--- |
| 5 | + |
| 6 | +# CLI Reference |
| 7 | + |
| 8 | +The MeshGuard CLI provides commands for managing agents, policies, and audit logs from the command line. |
| 9 | + |
| 10 | +## Installation |
| 11 | + |
| 12 | +### macOS (Homebrew) |
| 13 | + |
| 14 | +```bash |
| 15 | +brew tap meshguard/tap |
| 16 | +brew install meshguard |
| 17 | +``` |
| 18 | + |
| 19 | +### npm |
| 20 | + |
| 21 | +```bash |
| 22 | +npm install -g meshguard-cli |
| 23 | +``` |
| 24 | + |
| 25 | +### Direct Download |
| 26 | + |
| 27 | +Download binaries from [GitHub Releases](https://github.com/meshguard/meshguard-cli/releases). |
| 28 | + |
| 29 | +## Configuration |
| 30 | + |
| 31 | +Set your API key: |
| 32 | + |
| 33 | +```bash |
| 34 | +# Environment variable (recommended) |
| 35 | +export MESHGUARD_API_KEY=msk_xxx |
| 36 | + |
| 37 | +# Or use the config command |
| 38 | +meshguard config set api-key msk_xxx |
| 39 | +``` |
| 40 | + |
| 41 | +Set gateway URL (optional, defaults to cloud): |
| 42 | + |
| 43 | +```bash |
| 44 | +export MESHGUARD_GATEWAY_URL=https://dashboard.meshguard.app |
| 45 | + |
| 46 | +# Or for self-hosted |
| 47 | +meshguard config set gateway-url https://meshguard.yourcompany.com |
| 48 | +``` |
| 49 | + |
| 50 | +## Agent Commands |
| 51 | + |
| 52 | +### List Agents |
| 53 | + |
| 54 | +```bash |
| 55 | +meshguard agent list |
| 56 | +``` |
| 57 | + |
| 58 | +Output: |
| 59 | +``` |
| 60 | +ID NAME TRUST STATUS CREATED |
| 61 | +agent_abc123 customer-support verified active 2026-01-15 |
| 62 | +agent_def456 data-pipeline trusted active 2026-01-20 |
| 63 | +agent_ghi789 research-bot basic revoked 2026-01-10 |
| 64 | +``` |
| 65 | + |
| 66 | +Options: |
| 67 | +- `--trust <tier>` — Filter by trust tier |
| 68 | +- `--status <status>` — Filter by status (active/revoked) |
| 69 | +- `--json` — Output as JSON |
| 70 | + |
| 71 | +### Create Agent |
| 72 | + |
| 73 | +```bash |
| 74 | +meshguard agent create <name> [options] |
| 75 | +``` |
| 76 | + |
| 77 | +Examples: |
| 78 | +```bash |
| 79 | +# Basic agent |
| 80 | +meshguard agent create my-agent |
| 81 | + |
| 82 | +# With trust tier and tags |
| 83 | +meshguard agent create prod-agent --trust verified --tags production,api-access |
| 84 | + |
| 85 | +# Output token to file |
| 86 | +meshguard agent create my-agent --output token.txt |
| 87 | +``` |
| 88 | + |
| 89 | +Options: |
| 90 | +- `--trust <tier>` — Trust tier: `anonymous`, `basic`, `verified`, `trusted`, `privileged` |
| 91 | +- `--tags <tags>` — Comma-separated tags |
| 92 | +- `--output <file>` — Write token to file |
| 93 | +- `--json` — Output as JSON |
| 94 | + |
| 95 | +### Show Agent Details |
| 96 | + |
| 97 | +```bash |
| 98 | +meshguard agent show <agent-id> |
| 99 | +``` |
| 100 | + |
| 101 | +### Revoke Agent |
| 102 | + |
| 103 | +```bash |
| 104 | +meshguard agent revoke <agent-id> |
| 105 | +``` |
| 106 | + |
| 107 | +### Generate New Token |
| 108 | + |
| 109 | +```bash |
| 110 | +meshguard agent token <agent-id> |
| 111 | +``` |
| 112 | + |
| 113 | +## Policy Commands |
| 114 | + |
| 115 | +### List Policies |
| 116 | + |
| 117 | +```bash |
| 118 | +meshguard policy list |
| 119 | +``` |
| 120 | + |
| 121 | +Options: |
| 122 | +- `--json` — Output as JSON |
| 123 | + |
| 124 | +### Show Policy |
| 125 | + |
| 126 | +```bash |
| 127 | +meshguard policy show <policy-name> |
| 128 | +``` |
| 129 | + |
| 130 | +### Apply Policy |
| 131 | + |
| 132 | +```bash |
| 133 | +meshguard policy apply <file.yaml> |
| 134 | +``` |
| 135 | + |
| 136 | +Apply all policies from a directory: |
| 137 | +```bash |
| 138 | +meshguard policy apply ./policies/ |
| 139 | +``` |
| 140 | + |
| 141 | +### Validate Policy |
| 142 | + |
| 143 | +Check policy syntax without applying: |
| 144 | + |
| 145 | +```bash |
| 146 | +meshguard policy validate <file.yaml> |
| 147 | +``` |
| 148 | + |
| 149 | +### Test Policy |
| 150 | + |
| 151 | +Test how a policy evaluates for a specific agent and action: |
| 152 | + |
| 153 | +```bash |
| 154 | +meshguard policy test <agent-id> <action> [options] |
| 155 | +``` |
| 156 | + |
| 157 | +Examples: |
| 158 | +```bash |
| 159 | +# Test read action |
| 160 | +meshguard policy test agent_abc123 read:contacts |
| 161 | + |
| 162 | +# Test with resource |
| 163 | +meshguard policy test agent_abc123 write:email --resource "user@external.com" |
| 164 | + |
| 165 | +# Test with context |
| 166 | +meshguard policy test agent_abc123 execute:command \ |
| 167 | + --context '{"command": "rm -rf /"}' |
| 168 | +``` |
| 169 | + |
| 170 | +Output: |
| 171 | +``` |
| 172 | +Decision: DENY |
| 173 | +Policy: production-policy |
| 174 | +Rule: block-destructive-commands |
| 175 | +Reason: Destructive commands are not allowed |
| 176 | +``` |
| 177 | + |
| 178 | +### Delete Policy |
| 179 | + |
| 180 | +```bash |
| 181 | +meshguard policy delete <policy-name> |
| 182 | +``` |
| 183 | + |
| 184 | +## Audit Commands |
| 185 | + |
| 186 | +### Tail Audit Log |
| 187 | + |
| 188 | +Stream recent audit entries: |
| 189 | + |
| 190 | +```bash |
| 191 | +meshguard audit tail |
| 192 | +``` |
| 193 | + |
| 194 | +Options: |
| 195 | +- `-n <count>` — Number of entries (default: 20) |
| 196 | +- `-f, --follow` — Follow mode (stream new entries) |
| 197 | + |
| 198 | +### Query Audit Log |
| 199 | + |
| 200 | +Search audit entries with filters: |
| 201 | + |
| 202 | +```bash |
| 203 | +meshguard audit query [options] |
| 204 | +``` |
| 205 | + |
| 206 | +Options: |
| 207 | +- `--agent <name>` — Filter by agent name or ID |
| 208 | +- `--action <action>` — Filter by action |
| 209 | +- `--decision <allow|deny>` — Filter by decision |
| 210 | +- `--from <date>` — Start date (ISO 8601) |
| 211 | +- `--to <date>` — End date (ISO 8601) |
| 212 | +- `--limit <n>` — Max results (default: 100) |
| 213 | +- `--json` — Output as JSON |
| 214 | + |
| 215 | +Examples: |
| 216 | +```bash |
| 217 | +# Recent denials |
| 218 | +meshguard audit query --decision deny --limit 20 |
| 219 | + |
| 220 | +# Agent activity this week |
| 221 | +meshguard audit query --agent prod-agent --from 2026-01-27 |
| 222 | + |
| 223 | +# Email actions today |
| 224 | +meshguard audit query --action "write:email" --from 2026-02-01 |
| 225 | +``` |
| 226 | + |
| 227 | +### Trace Request |
| 228 | + |
| 229 | +Follow a complete request trace: |
| 230 | + |
| 231 | +```bash |
| 232 | +meshguard audit trace <trace-id> |
| 233 | +``` |
| 234 | + |
| 235 | +### Audit Statistics |
| 236 | + |
| 237 | +```bash |
| 238 | +meshguard audit stats [options] |
| 239 | +``` |
| 240 | + |
| 241 | +Options: |
| 242 | +- `--period <hours>` — Time period in hours (default: 24) |
| 243 | + |
| 244 | +### Export Audit Log |
| 245 | + |
| 246 | +Export for compliance/reporting: |
| 247 | + |
| 248 | +```bash |
| 249 | +meshguard audit export [options] |
| 250 | +``` |
| 251 | + |
| 252 | +Options: |
| 253 | +- `--from <date>` — Start date (required) |
| 254 | +- `--to <date>` — End date (defaults to now) |
| 255 | +- `--format <csv|json|parquet>` — Output format (default: csv) |
| 256 | +- `--output <file>` — Output file (defaults to stdout) |
| 257 | + |
| 258 | +Example: |
| 259 | +```bash |
| 260 | +meshguard audit export --from 2026-01-01 --to 2026-01-31 \ |
| 261 | + --format csv --output january-audit.csv |
| 262 | +``` |
| 263 | + |
| 264 | +## Config Commands |
| 265 | + |
| 266 | +### View Configuration |
| 267 | + |
| 268 | +```bash |
| 269 | +meshguard config list |
| 270 | +``` |
| 271 | + |
| 272 | +### Set Configuration |
| 273 | + |
| 274 | +```bash |
| 275 | +meshguard config set <key> <value> |
| 276 | +``` |
| 277 | + |
| 278 | +Available keys: |
| 279 | +- `api-key` — MeshGuard API key |
| 280 | +- `gateway-url` — Gateway URL |
| 281 | +- `output-format` — Default output format (text/json) |
| 282 | + |
| 283 | +### Get Configuration Value |
| 284 | + |
| 285 | +```bash |
| 286 | +meshguard config get <key> |
| 287 | +``` |
| 288 | + |
| 289 | +## Global Options |
| 290 | + |
| 291 | +These options work with all commands: |
| 292 | + |
| 293 | +| Option | Description | |
| 294 | +|--------|-------------| |
| 295 | +| `--json` | Output as JSON | |
| 296 | +| `--quiet` | Suppress non-essential output | |
| 297 | +| `--verbose` | Show detailed output | |
| 298 | +| `--gateway <url>` | Override gateway URL | |
| 299 | +| `--api-key <key>` | Override API key | |
| 300 | +| `--help` | Show help | |
| 301 | + |
| 302 | +## Exit Codes |
| 303 | + |
| 304 | +| Code | Meaning | |
| 305 | +|------|---------| |
| 306 | +| 0 | Success | |
| 307 | +| 1 | General error | |
| 308 | +| 2 | Invalid arguments | |
| 309 | +| 3 | Authentication error | |
| 310 | +| 4 | Policy denied | |
| 311 | +| 5 | Network error | |
| 312 | + |
| 313 | +## Examples |
| 314 | + |
| 315 | +### Complete Workflow |
| 316 | + |
| 317 | +```bash |
| 318 | +# 1. Create an agent |
| 319 | +meshguard agent create prod-bot --trust verified --tags production |
| 320 | + |
| 321 | +# 2. Create a policy file |
| 322 | +cat > policy.yaml << 'EOF' |
| 323 | +name: prod-bot-policy |
| 324 | +version: "1.0" |
| 325 | +appliesTo: |
| 326 | + tags: |
| 327 | + - production |
| 328 | +rules: |
| 329 | + - effect: allow |
| 330 | + actions: |
| 331 | + - "read:*" |
| 332 | + - effect: deny |
| 333 | + actions: |
| 334 | + - "delete:*" |
| 335 | + reason: "Deletion not allowed in production" |
| 336 | +defaultEffect: deny |
| 337 | +EOF |
| 338 | + |
| 339 | +# 3. Apply the policy |
| 340 | +meshguard policy apply policy.yaml |
| 341 | + |
| 342 | +# 4. Test it |
| 343 | +meshguard policy test <agent-id> delete:records |
| 344 | +# Output: Decision: DENY |
| 345 | + |
| 346 | +# 5. Monitor activity |
| 347 | +meshguard audit tail -f |
| 348 | +``` |
| 349 | + |
| 350 | +## Related |
| 351 | + |
| 352 | +- [Getting Started](/guide/getting-started) — Full setup guide |
| 353 | +- [Policies](/guide/policies) — Policy format and syntax |
| 354 | +- [Audit Logging](/guide/audit) — Audit configuration |
| 355 | +- [API Reference](/api/overview) — REST API documentation |
0 commit comments