> ## Documentation Index
> Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-changelog-august-13.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Logs

Search, download, and manage [organization audit logs](/info/audit-logs) from the CLI.

Search and download are available on **Start-Up** and **Enterprise** plans. Continuous S3 export is available on **Enterprise**.

Time values can be dates (`2026-06-01`) or timestamps (`2026-06-01T15:04:05Z`). Dates begin at midnight UTC.

<Note>
  The `kernel audit-logs export` group follows the current CLI implementation. Install a CLI release that includes this command group; availability depends on the release you have installed.
</Note>

## `kernel audit-logs search`

Search audit logs within a time window. Results are ordered newest first.

```bash theme={null}
kernel audit-logs search \
  --start 2026-06-01 \
  --end 2026-06-08 \
  --search /browsers \
  --limit 500 \
  --output json
```

If you omit the time flags, the command searches from 24 hours ago through now. The start is inclusive and the end is exclusive. Each time window can cover up to 30 days.

| Flag                         | Description                                                                                       |
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
| `--start <time>`             | Inclusive start. Defaults to 24 hours ago.                                                        |
| `--end <time>`               | Exclusive end. Defaults to now.                                                                   |
| `--search <text>`            | Search path, user ID, email, client IP, and status.                                               |
| `--method <method>`          | Return only requests that use this HTTP method.                                                   |
| `--exclude-method <method>`  | Exclude requests that use this HTTP method. GET remains excluded unless you pass `--include-get`. |
| `--include-get`              | Remove the default GET exclusion when `--method` is not set.                                      |
| `--service <service>`        | Filter by service.                                                                                |
| `--auth-strategy <strategy>` | Filter by authentication strategy.                                                                |
| `--user-id <id>`             | Add a user ID to the search. Repeat the flag for multiple IDs.                                    |
| `--limit <n>`                | Maximum total number of results. Defaults to `100`.                                               |
| `--output json`, `-o json`   | Output raw JSON array.                                                                            |

<Note>
  `--limit` controls the total number of CLI results. The CLI automatically requests API pages of up to 100 records until it reaches that limit or runs out of results.
</Note>

### Include GET requests

By default, the CLI returns matching requests for every HTTP method except GET. `--include-get` removes that default exclusion. `--method` selects exactly one method, so `--method GET` returns only GET requests.

```bash theme={null}
# Return all matching methods, including GET
kernel audit-logs search --include-get

# Return only GET requests
kernel audit-logs search --method GET
```

## `kernel audit-logs download`

Download matching audit logs in a time window as one gzip-compressed JSONL file.

```bash theme={null}
kernel audit-logs download \
  --start 2026-06-01 \
  --end 2026-07-01 \
  --to audit-june.jsonl.gz
```

`--start` and `--end` are required. The start is inclusive and the end is exclusive, and the time window can cover up to 30 days.

| Flag                         | Description                                                                                             |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `--start <time>`             | Inclusive start. Required.                                                                              |
| `--end <time>`               | Exclusive end. Required.                                                                                |
| `--search <text>`            | Search path, user ID, email, client IP, and status.                                                     |
| `--method <method>`          | Return only requests that use this HTTP method.                                                         |
| `--exclude-method <method>`  | Exclude requests that use this HTTP method. GET remains excluded unless you pass `--include-get`.       |
| `--include-get`              | Remove the default GET exclusion when `--method` is not set.                                            |
| `--service <service>`        | Filter by service.                                                                                      |
| `--auth-strategy <strategy>` | Filter by authentication strategy.                                                                      |
| `--user-id <id>`             | Add a user ID to the search. Repeat the flag for multiple IDs.                                          |
| `--to <path>`                | Output `.jsonl.gz` path. For the example above, the default is `audit-logs-20260601-20260701.jsonl.gz`. |
| `--force`                    | Replace an existing output file.                                                                        |

For example, `--start 2026-06-01 --end 2026-07-01` covers all of June in UTC.

### Download behavior

The CLI downloads up to 50,000 records per batch, verifies each batch's SHA-256 checksum, and automatically retries transient failures.

The requested output appears only after the full download succeeds. Failed downloads are removed, though a completed download may remain at `<output>.partial` if it can't be moved to the requested path.

Downloads don't resume: rerunning the command starts over. Existing files are replaced only when you pass `--force`.

## `kernel audit-logs export`

Manage S3 destinations that receive a continuous export of your organization's audit logs. The group is also available as `kernel audit-logs exports` and `kernel audit-logs export-destinations`.

Objects use the layout `<prefix>/destination_id=<destination>/org_id=<org>/date=<YYYY-MM-DD>/hour=<HH>/<window>-<chunk>.jsonl.gz`. Delivery is at-least-once.

Create a destination paused, configure the IAM trust and permissions, run `test`, and then run `resume`. The create response includes the `kernel_role_arn` and `external_id` values needed for the trust policy. The destination must use an organization-level credential; project-scoped API keys are refused.

### `kernel audit-logs export create`

Create an S3 audit log export destination. The destination is created paused.

```bash theme={null}
kernel audit-logs export create \
  --region us-east-1 \
  --bucket customer-audit-logs \
  --prefix audit-logs \
  --role-arn arn:aws:iam::123456789012:role/customer-audit-log-export \
  --output json
```

Use `--kms-key-id` when the destination should use SSE-KMS. The command always creates the destination with the `s3` type and `jsonl.gz` format.

| Flag                            | Description                                              |
| ------------------------------- | -------------------------------------------------------- |
| `--region <region>`             | AWS region of the destination bucket. Required.          |
| `--bucket <name>`               | Destination S3 bucket name. Required.                    |
| `--prefix <prefix>`             | Key prefix for exported objects; may be empty. Required. |
| `--role-arn <arn>`              | IAM role ARN Kernel assumes to deliver logs. Required.   |
| `--kms-key-id <id\|alias\|arn>` | KMS key ID, alias, or ARN for server-side encryption.    |
| `--output json`, `-o json`      | Output the raw JSON destination object.                  |

The human-readable output prints the destination details and the activation steps. Use JSON output when a script needs to capture `id`, `kernel_role_arn`, and `external_id`.

### `kernel audit-logs export list`

List audit log export destinations. Human-readable output includes the destination ID, bucket, prefix, region, status, last success, failure count, and last error.

```bash theme={null}
kernel audit-logs export list \
  --limit 20 \
  --output json
```

| Flag                       | Description                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------ |
| `--limit <n>`              | Maximum number of destinations to return, from `1` to `100`. Defaults to `20`.       |
| `--output json`, `-o json` | Output a JSON object with `destinations` and `next_offset` when another page exists. |

### `kernel audit-logs export get <id>`

Get details for one audit log export destination.

```bash theme={null}
kernel audit-logs export get y2kkbpcz1lg0h3q6yr8x4m7d \
  --output json
```

| Flag                       | Description                             |
| -------------------------- | --------------------------------------- |
| `--output json`, `-o json` | Output the raw JSON destination object. |

Without `--output json`, the command prints configuration, status, and delivery health fields such as `last_exported_cursor`, `last_success_at`, `last_error`, `last_error_at`, `consecutive_failures`, and `next_attempt_at`.

### `kernel audit-logs export update <id>`

Update one or more destination fields. Pass at least one update flag. The API validates the merged destination configuration, so a KMS key ARN must match the destination region.

```bash theme={null}
kernel audit-logs export update y2kkbpcz1lg0h3q6yr8x4m7d \
  --prefix audit-logs-v2 \
  --output json
```

To remove a configured KMS key and use bucket-default encryption:

```bash theme={null}
kernel audit-logs export update y2kkbpcz1lg0h3q6yr8x4m7d \
  --clear-kms-key
```

| Flag                            | Description                                                            |
| ------------------------------- | ---------------------------------------------------------------------- |
| `--region <region>`             | Update the AWS region of the destination bucket.                       |
| `--bucket <name>`               | Update the destination S3 bucket name.                                 |
| `--prefix <prefix>`             | Update the key prefix for exported objects.                            |
| `--role-arn <arn>`              | Update the IAM role ARN Kernel assumes to deliver logs.                |
| `--kms-key-id <id\|alias\|arn>` | Update the KMS key ID, alias, or ARN for server-side encryption.       |
| `--clear-kms-key`               | Remove the configured KMS key. Mutually exclusive with `--kms-key-id`. |
| `--output json`, `-o json`      | Output the raw JSON destination object.                                |

A successful update prints the updated destination. A `409 Conflict` means the destination changed concurrently; retrieve fresh state and retry with the intended fields.

### `kernel audit-logs export pause <id>`

Pause a destination so new delivery attempts stop.

```bash theme={null}
kernel audit-logs export pause y2kkbpcz1lg0h3q6yr8x4m7d \
  --output json
```

| Flag                       | Description                             |
| -------------------------- | --------------------------------------- |
| `--output json`, `-o json` | Output the raw JSON destination object. |

An S3 upload already in progress may still complete after the pause. Events recorded while paused are not exported.

### `kernel audit-logs export resume <id>`

Resume a destination. Delivery starts from the time of the resume; events recorded while paused are not exported.

```bash theme={null}
kernel audit-logs export resume y2kkbpcz1lg0h3q6yr8x4m7d \
  --output json
```

| Flag                       | Description                             |
| -------------------------- | --------------------------------------- |
| `--output json`, `-o json` | Output the raw JSON destination object. |

Use `resume` only after the destination's trust policy and permissions are configured and `test` succeeds.

### `kernel audit-logs export delete <id>`

Delete a destination and stop new delivery attempts.

```bash theme={null}
kernel audit-logs export delete y2kkbpcz1lg0h3q6yr8x4m7d
```

This command has no flags and does not support JSON output. An S3 upload already in progress may complete after the delete.

### `kernel audit-logs export test <id>`

Test a destination by assuming its role and writing a temporary probe object. The command exits non-zero when the test fails.

```bash theme={null}
kernel audit-logs export test y2kkbpcz1lg0h3q6yr8x4m7d \
  --output json
```

| Flag                       | Description                      |
| -------------------------- | -------------------------------- |
| `--output json`, `-o json` | Output the raw JSON test result. |

The result has `success` and `stage` fields. The stages are `assume_role`, `put_object`, and `complete`; customer-fixable failures use `assume_role_failed` or `put_object_failed`. A successful test reaches `complete`. The probe is deleted after the write when the role has `s3:DeleteObject`; grant that permission so test objects are cleaned up.

### Activation sequence

Use this sequence for every new destination:

1. Run `create`. Save the returned destination ID, `kernel_role_arn`, and `external_id`.
2. Update the customer role's trust policy to allow the returned Kernel role ARN with the returned `sts:ExternalId`.
3. Grant `s3:PutObject` and, preferably, `s3:DeleteObject` on the configured prefix. If KMS is configured, grant `kms:GenerateDataKey` and key-policy access.
4. Run `test <id>` and fix any `assume_role` or `put_object` failure.
5. Run `resume <id>` to start delivery from that point. There is no backfill.

After a plan downgrade, `list`, `get`, and `delete` remain available for cleanup, while delivery stops and `create`, `update`, and `test` require Enterprise.

## Aliases

You can also use `kernel audit-log`, `kernel auditlogs`, or `kernel auditlog`.