> For the complete documentation index, see [llms.txt](https://docs.alpha-security.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-security.app/user-guide/collector.md).

# Collector CLI

The collector (`al`) is the only thing that runs on your testing machine. It captures tool output and sends it to the Alpha server. Your workflow stays the same. The only change is prefixing commands with `al run`.

## Commands

### `al run`

Run a command with evidence capture:

```bash
al run nmap -sV 10.0.0.1
al run gobuster dir -u http://target -w /usr/share/wordlists/common.txt
al run -- netexec smb 10.0.0.0/24
```

The command executes exactly as you typed it. Alpha captures stdout through a PTY, so tools behave the same as in a normal terminal (colors, progress bars, interactive prompts all work). Use `--` before the command if its flags might conflict with `al` flags.

Tag runs for easier filtering later:

```bash
al run --tag recon nmap -sV 10.0.0.1
al run --tag privesc linpeas.sh
```

### `al shell`

Start a capture shell for hands-free recording:

```bash
al shell
```

Every command you type inside this shell is captured as a separate run. Recognized pentest tools get full output capture and parsing. Other commands are recorded as metadata only.

### `al query`

Pull entities from the server and pipe them into other tools:

```bash
al query host                    # list all hosts in the engagement
al query service                 # list services
al query credential              # list credentials
al query host --format ips       # output just IP addresses
al query host --format ips | netexec smb -   # pipe into netexec
```

Available kinds: `host`, `service`, `web_endpoint`, `credential`, `identity`, `finding`, `share`, `note`

Output formats: `json` (default), `ips`, `hosts`, `table`

### `al loot`

Show credentials and pinned loot:

```bash
al loot                          # masked by default (identifiers only)
al loot --reveal                 # show secret values (audited)
al loot --reveal --format user:pass   # output as user:pass pairs
al loot --reveal --format ntlm        # output NTLM hashes
```

Every `--reveal` call is audited server-side. There's no way to silently bulk-export secrets.

### `al enroll`

Register the collector with a server:

```bash
al enroll --server http://alpha.yourfirm.com --token <token>
```

### `al engagement`

Switch between engagements:

```bash
al engagement list
al engagement set <id>
```

### `al status`

Check the connection to the server and the active engagement:

```bash
al status
```

## Offline spool

If the server is unreachable (VPN dropped, server is down), the collector spools runs to disk and syncs them when connectivity returns. Nothing is lost.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alpha-security.app/user-guide/collector.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.