{"token_count": 1026}

# Investigate Activity from the CLI

Identity Security is available only with Teleport Enterprise.

`tctl investigate` searches the identity activity logs that Teleport Identity Security aggregates from Teleport and your integrations — the same data behind the Web UI [Investigate](https://goteleport.com/docs/identity-security/usage/investigate.md) view. Use it to trace who did what, from where, and when.

## Prerequisites

See [Identity Security from the Command Line](https://goteleport.com/docs/identity-security/cli.md) for the shared prerequisites and how the CLI authenticates to Access Graph. This command requires Access Graph v1.28.0 or later, and [Identity Activity Center](https://goteleport.com/docs/identity-security/access-graph/identity-activity-center.md).

## Explore with facets

A typical investigation starts broad and narrows: survey the shape of the data with facets, decide what to filter on, then pull the matching events.

Running `tctl investigate` returns events plus a facet summary of the matching data. To narrow a broad search before pulling events, ask for facets only:

```
$ tctl investigate --from=24h --facets-only
```

Facets show the top values for each field (user, event type, resource, source, IP, and more) so you can see what to filter on next.

## Filter with structured flags

Combine repeatable include filters; prefix any with `exclude-` to negate:

```
$ tctl investigate --user=alice@example.com --status=failure --from=7d
$ tctl investigate --event-type=session.start --exclude-source=okta
```

| Flag                                      | Description                                                   |
| ----------------------------------------- | ------------------------------------------------------------- |
| `--user`                                  | User (email for users, ID for bots). Repeatable.              |
| `--event-type`                            | Event type, e.g. `session.start`. Repeatable.                 |
| `--resource`, `--resource-kind`           | Target resource and kind (`ssh`, `kube`, …). Repeatable.      |
| `--status`                                | `success` or `failure`. Repeatable.                           |
| `--source`                                | Event source. Repeatable.                                     |
| `--ip`, `--country`, `--city`, `--region` | Origin filters. Repeatable.                                   |
| `--from`, `--to`                          | Time window. Default: `1d` to `now`.                          |
| `--limit`, `--order`                      | Cap results (default `100`) and order by time (`asc`/`desc`). |
| `--all-facets`, `--show-unmatched`        | Expand facet output.                                          |
| `--format`                                | `text`, `json`, `yaml`.                                       |

Every structured flag has an `--exclude-<flag>` counterpart. For the complete list (AWS, GitHub, Okta, Teleport-cluster, token, and user-agent filters), see the [CLI reference](https://goteleport.com/docs/reference/cli/tctl.md#tctl-investigate).

## Run a raw query

For expressions the structured flags cannot build, pass a raw Lucene query. `--query` is mutually exclusive with the structured filter flags:

```
$ tctl investigate --query 'identity_id:"alice@example.com" AND NOT status:"failure"'
```

Preview the query a set of flags would build without contacting the backend:

```
$ tctl investigate --user=alice@example.com --status=failure --print-query
```

## Filter by location

Restrict results to a radius (kilometers) around a point. All three geo flags are required together:

```
$ tctl investigate --latitude=37.8044 --longitude=-122.2712 --radius=25
```

## Use tctl investigate with an AI agent

---

TIP

To let an AI agent drive this command, install the matching Agent Skill:

```
$ npx skills add https://github.com/gravitational/teleport/tree/master/skills/teleport-investigate
```

---

## Next steps

- [tctl investigate reference](https://goteleport.com/docs/reference/cli/tctl.md#tctl-investigate)

## Troubleshooting

### --query is mutually exclusive with structured filter flags

Use either `--query` or the structured flags (`--user`, `--event-type`, …), not both. Remove the flags the error lists, or fold them into the raw query.

### geo filter requires all of --latitude, --longitude, and --radius

A location filter needs all three flags. Supply the missing one, or drop all three to search without a location filter.