Metadata-Version: 2.4
Name: conduct-cli
Version: 0.14.18
Summary: Runtime governance for AI agents. CLI for Conduct AI — secure, govern, install agents, manage projects, run tests
Author-email: Conduct AI <hello@conductai.ai>
License: Apache-2.0
Project-URL: Homepage, https://conductai.ai
Project-URL: Repository, https://github.com/sseshachala/conductai
Project-URL: Bug Tracker, https://github.com/sseshachala/conductai/issues
Keywords: ai,agents,automation,devops,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: psutil>=5.9
Requires-Dist: packaging>=23
Requires-Dist: tomlkit<1,>=0.13
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: jsonschema>=4.18; extra == "test"
Provides-Extra: booster
Requires-Dist: agent-booster[watch]>=0.6.6; extra == "booster"
Dynamic: license-file

<!-- mcp-name: io.github.sseshachala/conduct-cli -->
# conduct-cli

Official CLI for [Conduct AI](https://conductai.ai) — install AI agents, manage projects, run end-to-end tests, and enforce team AI policies with ConductGuard.

Runs on Linux, macOS, and Windows. Python 3.9–3.12.

![Conduct CLI demo — whoami, switch workspaces with Guard policy sync, and run an agent](assets/conduct-cli-demo.gif)

## Install

```bash
pip install conduct-cli
```

## Quick start

```bash
# Authenticate (one-time)
conduct login \
  --server https://api.conductai.ai \
  --token cond_agt_xxx \
  --workspace <workspace-id>

# Browse available agents
conduct playbooks

# Create a project and install all agents in one shot
conduct install-all --project DevOps --repo owner/repo

# List installed agents
conduct agents

# Run a test trigger on any agent
conduct test "PR Reviewer"
conduct test --all
```

## Commands

| Command | Description |
|---------|-------------|
| `conduct login` | Save connection config to `~/.conduct/config.json` |
| `conduct projects` | List all projects |
| `conduct create project <name>` | Create a project |
| `conduct delete project <name>` | Delete a project and all its agents |
| `conduct reset project <name>` | Delete all agents in a project (clean slate) |
| `conduct playbooks` | Browse available playbooks |
| `conduct playbooks <slug>` | Show required inputs for a playbook |
| `conduct install <slug>` | Install one agent from a playbook |
| `conduct install-all` | Install all 12 playbooks into a project |
| `conduct agents` | List all installed agents |
| `conduct test <name>` | Fire test trigger on an agent and stream results |
| `conduct test --all` | Test every playbook-based agent |

## Authentication

Generate an agent token from **Settings → Agents → Issue token** in the Conduct AI dashboard. Tokens start with `cond_agt_` and are stored as SHA-256 hashes — the plaintext is shown only once.

```bash
conduct login --server https://api.conductai.ai --token cond_agt_xxx --workspace <id>
```

## Install all agents

```bash
# Installs all 12 playbooks into a project, pointed at your GitHub repo
conduct install-all --project DevOps --repo myorg/myrepo
```

If the project doesn't exist it's created automatically. Use `--input key=value` to override any playbook input.

## Test agents

```bash
# Test a single agent (fires synthetic test payload, streams run events)
conduct test "Autopilot Quick"

# Test all playbook-based agents in sequence
conduct test --all
```

Exit code is `0` if all pass, `1` if any fail — works in CI.

---

## ConductGuard

ConductGuard is AI tool fleet management — your security team sets policies once and they're enforced automatically across every developer's Claude Code, Cursor, and Windsurf session.

### How it works

```
Admin configures policies and budgets in the Guard dashboard
    └─ developers are workspace members automatically — no invite step needed

Developer runs: conduct guard sync
    ├─ pulls latest policy to ~/.conduct/policy.json
    ├─ writes PreToolUse hook → ~/.conduct/hook.py
    ├─ registers hook → ~/.claude/settings.json
    └─ registers conductguard-mcp → ~/.claude/settings.json (mcpServers) + Codex

Every Claude Code tool call:
    ├─ PreToolUse hook fires (hook.py) → checks policy → block / warn / audit
    └─ Event posted async to ConductGuard API → visible in Activity feed
```

### Developer setup

```bash
pip install conduct-cli

# Authenticate (already done if you use Conduct)
conduct login --server https://api.conductai.ai --api-key <api-key>

# Sync Guard — installs hook + MCP, pulls policies
conduct guard sync
```

That's it. Policy enforcement is active from the next tool call.

### Guard commands

| Command | Description |
|---------|-------------|
| `conduct guard sync` | Pull latest policy, write hook to `~/.conduct/hook.py`, register hook + MCP |
| `conduct guard status` | Show today's spend, session count, and violations |
| `conduct guard audit [--since 7d]` | Print recent guard events in a table |
| `conduct verify [--evidence FILE] [--strict] [--format json]` | Map guard events to OWASP Agentic Top 10; exit 1 in CI if blocked events (--strict) |
| `conduct guard discover` | Scan local environment for AI agents; report Guard coverage % |
| `conduct guard discover --register` | Register discovered agents under Guard |

### Advisory mode

When advisory mode is enabled by your security admin, all policy violations are logged as "audited" instead of blocked — the developer sees a note but the tool call proceeds. The hook still posts every event to the audit log.

To check if advisory mode is active:
```bash
conduct guard sync   # shows "· advisory" badge if active
conduct guard status
```

### conduct verify

```bash
# Map last 24h of guard events to OWASP Agentic Top 10
conduct verify

# Use a saved evidence file
conduct verify --evidence ./conduct-evidence.json

# CI mode — exit 1 if any blocked events
conduct verify --strict

# JSON output for downstream tooling
conduct verify --format json
```

OWASP mapping: `no-rm-rf` → A04 Excessive Agency, `no-sudo` → A09 Privilege Escalation, `policy_signature_invalid` → A07 Insufficient Monitoring, etc. All 10 categories covered.

### How the PreToolUse hook works

When you run `conduct guard sync`, the CLI writes a Python script to `~/.conduct/hook.py` and registers it as a `PreToolUse` hook in `~/.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [{ "type": "command", "command": "python3 ~/.conduct/hook.py" }]
      }
    ]
  }
}
```

Before every tool call, Claude Code runs the hook. The hook:

1. Reads `tool_name` and `tool_input` from stdin (JSON)
2. Loads `~/.conduct/policy.json` (the team ruleset)
3. Matches the call against each rule (`match_tool`, `match_pattern`, `match_path_pattern`)
4. Takes the rule's action:
   - `block` — prints the policy message, exits with code `2` (Claude Code aborts the tool call)
   - `warn` — prints the message, exits `0` (tool call proceeds, developer is notified)
   - `audit` — posts an event silently, exits `0`
5. Posts an audit event to `POST /guard/events` asynchronously (fire-and-forget, never slows the tool call)

### How conductguard-mcp works

`conduct guard sync` also registers an MCP server entry in `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "conductguard": {
      "command": "conductguard-mcp",
      "args": ["--team", "<team-id>", "--token", "<member-token>"]
    }
  }
}
```

Claude Code starts `conductguard-mcp` as a subprocess on launch and keeps it running. It communicates via JSON-RPC 2.0 over stdin/stdout (MCP stdio transport).

The MCP server exposes three tools that Claude can call proactively:

| Tool | Description |
|------|-------------|
| `guard_status` | Returns team name, your email, number of active rules, and policy version |
| `guard_check` | Checks whether a specific tool + input would be blocked before Claude acts |
| `guard_sync` | Fetches the latest policy from the ConductGuard API and saves it locally |

**`guard_check` example** — Claude can self-check before a sensitive action:

```
guard_check(tool_name="bash", tool_input={"command": "rm -rf /tmp/build"})
→ ALLOWED — no policy rule matches 'bash'.

guard_check(tool_name="bash", tool_input={"command": "curl http://internal-api/secrets"})
→ BLOCKED — External network calls to internal endpoints are not permitted. [rule: no-internal-curl]
```

**`guard_sync` example** — after your security team pushes new rules:

```
guard_sync()
→ Policy synced — 12 rule(s) active (version: 2026-05-31T14:22:00Z).
```

### Policy file format

Policy is stored at `~/.conduct/policy.json` and synced from the server:

```json
{
  "team_id": "uuid",
  "version": "2026-05-31T14:22:00Z",
  "rules": [
    {
      "rule_id": "no-rm-rf",
      "match_tool": "bash",
      "match_pattern": "rm\\s+-rf",
      "match_path_pattern": null,
      "action": "block",
      "message": "Recursive deletes are not permitted. Use trash or targeted rm."
    },
    {
      "rule_id": "audit-prod-writes",
      "match_tool": "edit,write",
      "match_path_pattern": "/prod/",
      "match_pattern": null,
      "action": "warn",
      "message": "Writing to prod directory — make sure this is intentional."
    }
  ]
}
```

### Keeping policy up to date

Run `conduct guard sync` after your security team updates rules in the ConductGuard dashboard. The sync command pulls the latest policy, rewrites the hook, and re-registers the MCP entry in any newly detected AI tool configs.

Sync also migrates the Codex Conduct provider to `CONDUCT_GATEWAY_TOKEN`, separate
from provider-specific `OPENAI_API_KEY` overrides. The managed shell environment
refreshes this credential on every sync. On macOS, sync also updates the current
login session's app-launch environment for newly launched desktop apps. Run sync
again after a new macOS login before opening Codex from the Dock.

Fully quit and reopen Codex after syncing. For terminal launches, open a new shell
or source `~/.conduct/env` first (`~/.conduct/env.ps1` in PowerShell). Sync cannot
change the environment of an already-running process. `--no-codex-proxy` leaves
the Codex provider and desktop launch environment unchanged. This is client
configuration, not protection against a user deliberately bypassing the Gateway.

### Reported Model Usage

After upgrading the CLI, run `conduct guard sync` and restart Claude Code,
Codex, and Copilot CLI so their hook registrations are reloaded. Upgrading the
package alone does not update already-installed hooks.

Flight Recorder records available model usage in separate `session_usage`
events, not on every Bash/Edit/Read action. Codex cumulative counters and Claude
message usage are collected incrementally and deduplicated; cache and reasoning
tokens are counted once. Copilot reports persisted shutdown counters, so current
session tokens may remain unavailable until shutdown. Missing telemetry is not
zero, and these reports are not Gateway receipts or provider invoices.

The first collection establishes a baseline rather than importing historical
usage into the active workspace. Start/stop/end hooks and later tool actions
recover delayed transcript writes. Unsupported or missing transcript formats
remain unavailable; no token counts are inferred from tool output.

Deploy the API supporting multi-client `/guard/events/session-usage` reports
before releasing this CLI change. Production verification requires one fresh
session per client after sync; existing tool rows are not retroactively filled.

### Copilot CLI

On macOS, Linux, and Windows, `conduct guard sync` detects the `copilot` executable
or its configuration directory independently of the VS Code extension. It creates
or updates the Conduct MCP entry and installs managed hooks at
`~/.copilot/hooks/conduct-guard.json` (or `$COPILOT_HOME/hooks/conduct-guard.json`).
Other MCP servers and hook files are preserved. Restart Copilot after syncing.

Pre-tool hooks use the shared Guard policy engine; blocked calls return a Copilot
deny decision. Allowed calls retain Copilot's own permission checks. Post-tool
hooks record success or failure as separate audit events linked by session ID;
they do not infer model token counts. This does not configure or replace the
GitHub-hosted model provider, and does not imply Gateway spend coverage.

The adapter returns a deny decision if its Guard subprocess exceeds 20 seconds,
before Copilot's configured 30-second hook timeout. Approval checks exceeding
that bound are denied and must be retried. Copilot's outer hook timeout is itself
fail-open; user hooks can also be disabled. These are not tamper-proof enterprise
policy hooks. Use a current Copilot CLI release supporting user hooks and the
`exec`/`args` command-hook format.

```bash
# Add to a daily cron or run manually after policy changes
conduct guard sync
```

---

## Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "conduct": {
      "command": "conduct-mcp",
      "args": []
    },
    "conductguard": {
      "command": "conductguard-mcp",
      "args": ["--team", "<workspace-id>", "--token", "<member-token>"]
    }
  }
}
```

Run `conduct login` first — `conduct-mcp` reads credentials from `~/.conduct/config.json`. Get your agent token from **Settings → Agents → Issue token** in the Conduct AI dashboard.

---

## VS Code + GitHub Copilot

Install from the MCP registry directly in VS Code:

```bash
code --add-mcp '{"name":"conduct","command":"conduct-mcp","args":[]}'
code --add-mcp '{"name":"conductguard","command":"conductguard-mcp","args":["--team","<workspace-id>","--token","<member-token>"]}'
```

Or add to `.vscode/mcp.json` in your repo:

```json
{
  "servers": {
    "conduct": {
      "type": "stdio",
      "command": "conduct-mcp",
      "args": []
    },
    "conductguard": {
      "type": "stdio",
      "command": "conductguard-mcp",
      "args": ["--team", "<workspace-id>", "--token", "<member-token>"]
    }
  }
}
```

Once wired, GitHub Copilot can list your agents, trigger workflows, and check Guard policies — the same tools available in Claude Code and Cursor.

**Prerequisites:** `pip install conduct-cli` + `conduct login`

---

## Links

- Dashboard: [conductai.ai](https://conductai.ai)
- Docs: [conductai.ai/docs](https://conductai.ai/docs)
- Issues: [github.com/sseshachala/conductai/issues](https://github.com/sseshachala/conductai/issues)
