audit:*

Manage audit delivery channels in clonio.json. Channels define where Clonio sends audit logs and process logs after each operation.

Commands

audit:add

Adds a new audit delivery channel to the clonio.json configuration file in the current directory.

Usage

clonio audit:add [<name>] [options]

All arguments and options are optional. Any value not supplied via a flag will be collected interactively.

Interactive flow

When run without flags the command walks through each field in order:

1. Name — A unique identifier for the channel. Must match [a-z0-9_-]+ (max 64 chars).
2. Type — Selected from a list of supported channel types.
3. Type-specific fields — Prompted based on the chosen type (see below). Network channels (s3, email, ms_teams, slack, ntfy) finish with "Override retry settings?" (default: no).
4. Summary — A table of the collected values (secrets masked).
5. Save this channel? — Confirm to write the channel to clonio.json; answering no cancels without changes.

Every type-specific field has a matching option. Values passed as options are not prompted again.

Channel types

Options

Common

Local (--type=local)

S3 (--type=s3)

Default retry settings: 5 attempts, 1000 ms initial delay, multiplier 2, max delay 30000 ms.

Email (--type=email)

Default retry settings: 3 attempts, 500 ms initial delay, multiplier 2, max delay 10000 ms.

Microsoft Teams / Slack (--type=ms_teams or --type=slack)

Default retry settings: 3 attempts, 500 ms initial delay, multiplier 2, max delay 10000 ms.

ntfy (--type=ntfy)

Topics on the public ntfy.sh server are readable by anyone who knows the name. Use a hard-to-guess topic or a self-hosted server for sensitive environments.

Default retry settings: 3 attempts, 500 ms initial delay, multiplier 2, max delay 10000 ms.

Stack (--type=stack)

A stack has no options. The command lists the existing channels and asks for "Channels to include (comma-separated)". At least one other channel must already exist; otherwise the command fails with a config error.

Exit codes

Examples

# Interactive
clonio audit:add

# Non-interactive: local channel, enabled immediately
clonio audit:add logs --type=local --local-path='./clonio-logs/{year}/{month}' --enable

# S3 channel (the secret key is prompted, so it stays out of shell history)
clonio audit:add s3-backup --type=s3 --s3-endpoint=https://s3.amazonaws.com \
  --s3-bucket=my-bucket --s3-region=eu-west-1 --s3-access-key=AKIA... \
  --s3-path-prefix='clonio/{year}/{month}/'

# Slack channel (the webhook URL is prompted)
clonio audit:add slack-alerts --type=slack

# Email with multiple recipients
clonio audit:add email-report --type=email --mail-host=smtp.example.com --mail-port=587 \
  --mail-encryption=tls --mail-username=bot@example.com --mail-from-address=bot@example.com \
  --mail-from-name="Clonio" --mail-to="alice@example.com,bob@example.com"

# Fan out to existing channels (channel names are prompted)
clonio audit:add production --type=stack

audit:update

Updates an existing audit delivery channel. The channel type cannot be changed — delete and re-add the channel to switch types.

Usage

clonio audit:update [<name>]

If name is omitted and only one channel exists, it is selected automatically. With multiple channels, an interactive selection prompt is shown.

All type-specific fields are re-prompted with the current values as defaults. Secrets display as •••••••• — press Enter to keep the existing value, or enter a new one to replace it.

A diff table is shown before the final confirmation so you can review exactly what will change.

Options

Exit codes

Examples

# Interactive selection
clonio audit:update

# Update specific channel
clonio audit:update s3-backup

audit:delete

Deletes an audit delivery channel from clonio.json. If the channel is referenced by audit.use, it is automatically removed from that list as well.

Usage

clonio audit:delete [<name>] [--force]

If name is omitted and only one channel exists, it is selected automatically. With multiple channels, an interactive selection prompt is shown.

A warning is displayed if the channel is currently in audit.use. Stack channels that reference the deleted channel are not changed; remove the name from their channels list with audit:update.

Options

Exit codes

Examples

# Interactive selection
clonio audit:delete

# Delete specific channel
clonio audit:delete logs

# Delete without confirmation (e.g. in scripts)
clonio audit:delete logs --force

audit:list

Lists all configured audit delivery channels.

Usage

clonio audit:list

Outputs a table with columns: Name, Type, Active (★ if the channel is listed in audit.use), Details.

The Details column shows a summary appropriate to the channel type:

• Local: audit log path
• S3: s3://bucket/path-prefix
• Email: first recipient address
• Teams / Slack: (webhook — encrypted)
• ntfy: server-url / topic
• Stack: comma-separated child channel names

Exit codes

Examples

clonio audit:list

Notes

Stack Channel

The stack type fans out delivery to multiple child channels. Use it when you want to deliver audit artefacts to several destinations at once.

Example:

"production": {
    "type": "stack",
    "channels": ["local", "s3-backup", "slack-notify"]
}

Active Channels (audit.use)

The audit.use array selects which channels actively deliver audit artefacts:

"audit": {
    "use": ["local"],
    "channels": { ... }
}

Channels configured in audit.channels but not listed in audit.use are inert — they will not deliver. To deliver to multiple channels, list them in use or define a stack channel and reference it. The --audit-channel CLI flag overrides audit.use for a single run.

Use --enable when adding a channel to add it to audit.use in one step:

clonio audit:add logs --type=local --local-path=./ --enable

Secret encryption

All secrets (S3 secret keys, SMTP passwords, webhook URLs, ntfy tokens) are stored encrypted using Laravel's Crypt facade:

encrypted:<base64-encoded-ciphertext>

This requires APP_KEY to be set in the environment (.env or exported). Passing secrets via CLI flags (--s3-secret-key=, --mail-password=, --webhook-url=, --ntfy-token=) is supported but prints a warning, because the value may end up in shell history. Prefer the interactive prompt.

What each channel delivers

Each channel has independent control over whether it delivers the audit artefacts and the process log:

audit:add always uses these defaults. To change them, set the delivers_audit and delivers_process_log boolean keys directly in clonio.json:

{
  "audit": {
    "use": ["local"],
    "channels": {
      "local": {
        "type": "local",
        "path": "./",
        "delivers_audit": true,
        "delivers_process_log": false
      },
      "slack-alerts": {
        "type": "slack",
        "webhook_url": "encrypted:...",
        "delivers_audit": true,
        "delivers_process_log": true
      }
    }
  }
}

Note: audit:update rewrites the channel from the prompted fields and currently drops these two keys. Re-add them to clonio.json after running audit:update on such a channel.

clonio.json location

All commands read from and write to clonio.json in the current working directory. Run commands from the root of the project whose configuration you want to manage.

Path templates

Local and S3 path fields support the following placeholders:

Retry settings

S3, email, Teams, Slack, and ntfy channels support optional retry configuration. During audit:add, you are prompted with "Override retry settings?" (default: no). If yes, four values are collected, pre-filled with the type defaults listed above:

audit:update preserves existing retry settings automatically — edit clonio.json directly to change retry values after the channel is created.