CLI Agent (NCTL AI)

brew tap nirmata/tap
brew install nctl

nctl ai

Using nctl AI requires authentication with Nirmata Control Hub to access 
AI-enabled services. Please enter your business email to sign up for a 
free trial, or sign in to your account

Enter email: ****@******.com

A verification code has been sent to your email.
Enter verification code: ******

Email verified successfully!
Your credentials have been fetched and successfully saved.

👋 Hi, I am your Nirmata AI Platform Engineering Assistant!

I can help you automate security, compliance, and operational best practices 
across your clusters and pipelines.

💡 Here are some tasks I can do for you, or ask anything:
  ▶ scan clusters
  ▶ generate policies and tests
  ▶ optimize costs

💡 type 'help' to see commands for working in nctl ai

───────────────────────────────────────────────────────────────────────────────────────
>
───────────────────────────────────────────────────────────────────────────────────────

nctl ai --prompt "create a policy that requires all pods to have resource limits"

servers:
  - name: resend-email
    command: node
    args:
      - /path/to/directory/mcp-send-email/build/index.js
    env:
      RESEND_API_KEY: your_api_key_here
      SENDER_EMAIL_ADDRESS: example@email.com
      REPLY_TO_EMAIL_ADDRESS: another_example@email.com
    capabilities:
      tools: true
      prompts: false
      resources: false
      attachments: true

~/.nirmata/nctl/skills/
  └── kyverno-cli-tests/
      └── SKILL.md
  └── my-custom-skill/
      └── my-first-custom-skill
          └── SKILL.md

# Kyverno Tests (Unit Tests)

Kyverno CLI tests are used to validate policy behaviors against sample "good" and "bad" resources. Carefully follow the instructions and best practices below when running Kyverno CLI tests:

- Always use the supplied tools to generate and execute Kyverno tests.
- **Testing:** When creating test files for Kyverno policies, always name the test file as "kyverno-test.yaml".
- **Test Execution:** After generating a Kyverno policy, test file (kyverno-test.yaml), and Kubernetes resource files, always run the "kyverno test" command via the `nctl_test` wrapper tool in the policy folder to validate that the policy works correctly with the test scenarios. Utilize the argument `--output-format json` in order to capture rich output. If ANY expected or actual results are recorded as "Unknown", check the test file and/or resource file(s) for resource name mismatches, or for syntax errors in the resource file. Do not ignore any such warnings. Re-execute the test after any changes to prove that the test now works.
-  **Test Results:** all Kyverno tests must `Pass` for a successful outcome. Stop when all tests pass.
-  **Understanding Policy Fail vs Test Fail**: a `Pass` result for a Kyverno test output indicates the test passed i.e. the result matches the expected policy result (pass, fail, etc.), and does not mean that the Policy has passed. Do not get confused by all tests passing. Refer to the table below to understand the difference between the policy result and the test result:
   -  Policy Result: `Pass`; Expected Result: `Pass`; Test Result: `Pass`
   -  Policy Result: `Pass`; Expected Result: `Fail`; Test Result: `Fail`
   -  Policy Result: `Fail`; Expected Result: `Pass`; Test Result: `Fail`
   -  Policy Result: `Fail`; Expected Result: `Fail`; Test Result: `Pass`
-  Only test for `Audit` mode. Do not try to update policies and test for `Enforce` mode.

## Test File Organization

Organize Kyverno CLI test files in a `.kyverno-test` sub-directory where the policy YAML is contained.

Sample test folder structure:

```
pod-security/
  ├── disallow-privileged-containers/
  │   ├── disallow-privileged-containers.yaml
  │   └── .kyverno-tests/
  │       ├── kyverno-test.yaml
  │       ├── resources.yaml
  │       └── variables.yaml
  └── other-policies/
```

# Custom Policy Validator

Use this script to validate policies against our internal standards:

```bash
#!/bin/bash
# Validate policy naming conventions
grep -q "^metadata:\s*name:\s*[a-z-]*$" "$1" || echo "Policy name must use lowercase with hyphens"
```

Run this validator before committing policies to ensure they meet our standards.

nctl ai --mcp-server

{
  "mcpServers": {
    "nctl": {
      "command": "nctl",
      "args": ["ai", "--mcp-server", "--token", "YOUR_NIRMATA_TOKEN"]
    }
  }
}

nctl ai --help

Agentic AI powered workflows

Usage:
  nctl ai [flags]

Examples:

  # Run an interactive AI workflow.
  nctl ai

  # Run an interactive AI workflow with a specific prompt.
  nctl ai --prompt "generate a Kyverno policy that enforces all pods have a 'team' label"

  # Allow AI to access additional directories.
  nctl ai --allowed-dirs "/path/to/policies,/tmp" --prompt "create pod security policies in /path/to/policies"

  # Use a custom MCP configuration file.
  nctl ai --mcp-config "/path/to/custom/mcp.yaml"

  # Start nctl as an MCP server for external AI clients.
  nctl ai --mcp-server

  # Start MCP server with verbose logging.
  nctl ai --mcp-server -v 1


Flags:
      --allowed-dirs strings     additional directories the AI can access (comma-separated)
      --delete-session string    delete a session by ID
      --force                    allow destructive operations in non-interactive mode (requires both --prompt and --skip-permission-checks)
  -h, --help                     help for ai
      --insecure                 allow connection to a Nirmata server with a insecure certificate (not recommended)
      --list-sessions            list all available sessions
      --max-tool-calls int       maximum number of tool calls to make (default 200)
      --mcp-config string        path to MCP configuration file (default: ~/.nirmata/nctl/mcp.yaml)
      --mcp-server               run a MCP (Model Context Protocol) server on stdio for Nirmata AI tools
      --new-session              create a new session (default: true) (default true)
      --prompt string            prompt for the AI workflow
      --resume-session string    ID of session to resume (use 'latest' for the most recent session)
      --skip-permission-checks   skip permission checks for tools (not recommended)
      --token string             the Nirmata API Login Key (env NIRMATA_TOKEN)
      --url string               the Nirmata server base URL (env NIRMATA_URL)
      --usage-details            show AI usage details and exit

Global Flags:
  -v, --v Level   number for the log level verbosity