> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cynative.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cynative Agents: Named Prompts for Security Research

> Agents are Markdown files that supply the prompt for a Cynative run. Use built-in agents, shadow them, or write your own for repeatable security research.

An **agent** is a Markdown file that supplies the prompt for a Cynative run. Where a free-form question is useful for exploratory or one-off research, an agent turns a recurring task — privilege escalation paths, public data store exposure, supply chain risk — into a versioned, reviewable artifact you can run consistently across environments. Because the prompt lives in a file, it can be code-reviewed, committed to a repository, and shared with the rest of your team, while the run itself stays read-only and tied to your own credentials.

## Two sources of agents

Agents come from exactly two places, resolved in order — first match wins:

| Precedence | Source | Location |
| - | - | - |
| 1 | user | `~/.cynative/agents/` |
| 2 | built-in | embedded in the binary |

The binary ships 45 built-in agents covering AWS, Azure, GCP, GitHub, and Kubernetes. To add your own, create the directory and write Markdown files into it. Cynative does not create the directory for you:

```bash theme={null}
mkdir -p ~/.cynative/agents
```

Any file you place there is immediately available as `--agent <filename-without-extension>`. A user agent with the same name as a built-in takes precedence — see [Shadowing](#shadowing) below.

## Running agents

Pass `--agent <name>` with `-p` for a single non-interactive run, with an optional task to scope it further, or without `-p` to seed an interactive session:

```bash theme={null}
cynative -p --agent aws-public-datastores
cynative -p --agent aws-public-datastores "AWS account 128149835728 only"
cynative --agent aws-public-datastores   # seeds interactive session
```

The optional positional argument after the agent name is your **task** — a scoping instruction passed alongside the agent's own prompt. When you provide one, it appears in the prompt as a `user instruction:` section between the agent's description and its body. When you omit it, that section is left out entirely.

## Listing and inspecting agents

```bash theme={null}
cynative agents list           # every agent, source, status
cynative agents show <name>    # print the exact file
```

`agents list` shows every agent from both sources, with its source and status. `agents show` writes the file bytes to stdout and the source path to stderr — useful for review, and for copying a built-in as the basis for a custom agent. Neither command reads your configuration or touches credentials, so both work on a fresh install before Cynative is configured.

When a user agent shadows a built-in of the same name, `agents list` marks the loser:

```
NAME    DESCRIPTION                 SOURCE   STATUS
alpha   Your copy of alpha.         user     active
alpha   The built-in alpha.         builtin  shadowed by user
beta    A built-in agent.           builtin  active
broken                              user     invalid (blocking)
```

A file that is found but unusable — malformed, unreadable, oversized, a symlink, or not a regular file — appears as `invalid (blocking)`. It still claims the name, so the run fails with an error naming the file. Resolution never falls through to the built-in.

## Composing with other flags

`--agent` composes with the rest of Cynative's flags:

| Combination | Effect |
| - | - |
| `--agent` + `-p` | Single non-interactive run; exits with a verdict code. |
| `--agent` + `-p` + `--auto-approve` | Fully unattended; skips the per-call keystroke. Suitable for CI. |
| `--agent` + `--verbose` | Streams each inner tool call as it runs. |
| `--agent` + `--config` | Uses an alternate config file for LLM and connector settings. |
| `--agent` + piped stdin | Piped bytes are fenced in `<piped_input>` tags and treated as untrusted data to analyse — the agent file is already supplying the instruction. |

For example, to triage a findings file with an agent in a CI pipeline:

```bash theme={null}
cat findings.json | cynative -p --auto-approve --agent triage-findings
```

## Trust

Agents come only from `~/.cynative/agents/` and the binary. Selection is always explicit by name: **the model cannot introduce an agent or choose one on its own.** An agent only supplies text — approvals, connector authorization, and the read-only ceilings are all enforced by Cynative when each tool call runs, regardless of what the agent's prompt says. An agent cannot reach anything your credentials do not already allow.

<Note>
  Every run prints which agent file was used and its source path — for example:

  ```
  Agent: my-aws-public-datastores  [user: /home/you/.cynative/agents/my-aws-public-datastores.md]
  ```

  `cynative agents list` shows the same information ahead of time, and every audited tool call records the agent's name, source, and file digest so a finding can be traced back to the exact prompt that produced it.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.