Installation

To install and run the Tracecat CLI, you can use either pipx or Docker.

pipx

pipx is a tool that lets you install and run Python applications in isolated environments. It’s conceptually similar to npx.

First, install pipx if you don’t have it. Full installation instructions can be found here.

Then install the Tracecat CLI using the following command:

pipx install "git+https://github.com/TracecatHQ/tracecat.git#subdirectory=cli&egg=tracecat_cli"

This installs the CLI to /path/to/home/.local/bin/tracecat. You should see something like this if done correctly:

❯ pipx install "git+https://github.com/TracecatHQ/tracecat.git#subdirectory=cli&egg=tracecat_cli"


  installed package tracecat_cli 0.1.4.dev0, installed using Python 3.12.4
  These apps are now globally available
    - tracecat
done! ✨ 🌟 ✨
❯ which tracecat
/Users/daryllim/.local/bin/tracecat

Workflow Management

The tracecat workflow command suite allows you to manage workflows within the system. Below are the available commands and options to control and interact with workflow processes.

Listing Workflows

To list all the workflows available in the system, use the list command.

tracecat workflow list

Creating a Workflow

This command is used to create a new workflow with specified parameters, which can be customized through various options.

tracecat workflow create WORKFLOW_ID [OPTIONS]
OptionShortcutParameterDescriptionDefault
--title-tTEXTTitle of the workflow.None
--description-dTEXTDescription of the workflow.None
--activateActivate the workflow immediately after creation.
--webhookActivate the webhook for the workflow.
--commit-cPATHCreate with a specified workflow definition.None

For example,

Commit, activate, and enable webhook for a workflow
tracecat workflow create --commit /path/to/workflow.yml --activate --webhook

Committing changes to a Workflow

To make changes to a workflow definition, use the commit command.

tracecat workflow commit WORKFLOW_ID [OPTIONS]
OptionShortcutParameterDescriptionDefault
--file-fPATHPath to the workflow definition YAML file.None

The changes here are reflected in Tracecat’s internal workflow definition, and the UI workflow graph,

Activating a Workflow

Make a workflow available for execution using the up command. A decativated workflow or webhook will reject any incoming requests.

tracecat workflow up WORKFLOW_ID
OptionShortcutDescriptionDefault
--webhookActivate its webhook as well.
--helpShow help message and exit.

Running a Workflow

tracecat workflow run WORKFLOW_ID [OPTIONS]
OptionShortcutDescriptionDefault
--data-dJSON Payload to send.None
--proxyIf set, run the workflow through the external-facing webhook.
--testIf set, run the workflow with runtime action tests.

For example:

tracecat workflow run wf-XXXXXXXXXXXXXXXXXXXXXXXXXX --data '{"my": "data", "for": "the", "workflow": "run"}'

To run with action tests, use the --test flag:

tracecat workflow run wf-XXXXXXXXXXXXXXXXXXXXXXXXXX --data '{"my": "data", "for": "the", "workflow": "run"}' --test

On a successful run, you will see

{"status": "ok" }

You can view the workflow execution status in the temporal UI (default: http://localhost:8088).

Inspecting a Workflow

tracecat workflow inspect WORKFLOW_ID

You can find detailed information about a specific workflow using this command. You can find the actions and webhook information associated with the workflow.

❯ tracecat workflow inspect wf-741117aa4bcf4465b051d5c029445b85
{
    'id': 'wf-741117aa4bcf4465b051d5c029445b85',
    'title': 'Update Crowdstrike alerts via Slack',
    'description': 'Receives a Slack action and updates Crowdstrike alerts based on\n`alert_ids` and `status` provided in the Slack action payload.\n',
    'status': 'online',
    'actions': {
        'act:wf-741117aa4bcf4465b051d5c029445b85:extract_slack_payload': {
            'id': 'act:wf-741117aa4bcf4465b051d5c029445b85:extract_slack_payload',
            'type': 'core.transform.reshape',
            'title': 'Extract slack payload',
            'description': '',
            'status': 'offline',
            'inputs': {'value': {'username': '${{ TRIGGER.username }}', 'alert_id': '${{ TRIGGER.alert_id }}', 'old_status': '${{ TRIGGER.old_status }}', 'new_status': '${{ TRIGGER.new_status }}'}},
            'key': 'act:wf-741117aa4bcf4465b051d5c029445b85:act:wf-741117aa4bcf4465b051d5c029445b85:extract_slack_payload'
        },
        'act:wf-741117aa4bcf4465b051d5c029445b85:update_crowdstrike_alerts': {
            'id': 'act:wf-741117aa4bcf4465b051d5c029445b85:update_crowdstrike_alerts',
            'type': 'integrations.crowdstrike.update_crowdstrike_alert_status',
            'title': 'Update crowdstrike alerts',
            'description': '',
            'status': 'offline',
            'inputs': {'alert_ids': ['${{ ACTIONS.extract_slack_payload.result.alert_id }}'], 'status': '${{ ACTIONS.extract_slack_payload.result.new_status }}'},
            'key': 'act:wf-741117aa4bcf4465b051d5c029445b85:act:wf-741117aa4bcf4465b051d5c029445b85:update_crowdstrike_alerts'
        },
        'act:wf-741117aa4bcf4465b051d5c029445b85:send_slack_notification': {
            'id': 'act:wf-741117aa4bcf4465b051d5c029445b85:send_slack_notification',
            'type': 'integrations.chat.slack.post_slack_message',
            'title': 'Send slack notification',
            'description': '',
            'status': 'offline',
            'inputs': {
                'channel': '${{ SECRETS.slack.SLACK_CHANNEL }}',
                'text': 'CrowdStrike alerts updated',
                'blocks': [
                    {'type': 'header', 'text': {'type': 'plain_text', 'text': '${{ ACTIONS.extract_slack_payload.result.username }} changed status of alert', 'emoji': True}},
                    {
                        'type': 'section',
                        'fields': [
                            {'type': 'mrkdwn', 'text': '*Alert ID:* ${{ ACTIONS.extract_slack_payload.result.alert_id }}'},
                            {'type': 'mrkdwn', 'text': '*Old status:* ${{ ACTIONS.extract_slack_payload.result.old_status }}'},
                            {'type': 'mrkdwn', 'text': '*New status:* ${{ ACTIONS.extract_slack_payload.result.new_status }}'}
                        ]
                    }
                ]
            },
            'key': 'act:wf-741117aa4bcf4465b051d5c029445b85:act:wf-741117aa4bcf4465b051d5c029445b85:send_slack_notification'
        }
    },
    'object': { ... },  # This is the frontend graph object, omitted for brevity
    'owner_id': 'default-tracecat-user',
    'version': 1,
    'webhook': {
        'owner_id': 'default-tracecat-user',
        'created_at': '2024-06-25T18:16:56.483047Z',
        'updated_at': '2024-06-25T18:16:56.514445Z',
        'id': 'wh-9a636f9125fb4cc4876c19e12001a211',
        'secret': '<redacted>',
        'status': 'online',
        'entrypoint_ref': None,
        'filters': {},
        'method': 'POST',
        'workflow_id': 'wf-741117aa4bcf4465b051d5c029445b85',
        'url': 'http://localhost:8000/webhooks/wf-741117aa4bcf4465b051d5c029445b85/<redacted>'
    },
    'schedules': [],
    'entrypoint': 'act:wf-741117aa4bcf4465b051d5c029445b85:extract_slack_payload'
}

Viewing Workflow Cases

Outputs the cases associated with a workflow.

tracecat workflow cases WORKFLOW_ID
OptionShortcutDescriptionDefault
--table-tDisplay as a table.

Deleting Workflows

tracecat workflow delete [WORKFLOW_IDS]

This action is irreversible and will remove the workflow and all its associated actions and workflow definitions from the system. Use with caution.

Secrets Management

The tracecat secrets command allows you to manage workflows within the system. Below are the available commands and options to control and interact with workflow processes.

Creating Secrets

Creates a secret with specified key-value pairs.

tracecat secrets create SECRET_NAME KEYVALUES
ArgumentTypeDescriptionDefaultRequired
secret_nameTEXTSecret name, can include multiple key-value pairs.NoneYes
keyvaluesKEYVALUES…Space-separated KEY-VALUE items, e.g., KEY1=VAL1 KEY2=VAL2 ....NoneYes

For example,

tracecat secrets create slack SLACK_CHANNEL=channel-name SLACK_BOT_TOKEN=token SLACK_WEBHOOK=webhook_url

Listing Secrets

View all the secrets stored in Tracecat’s secret manager.

tracecat secrets list

Deleting Secrets

Delete a secret from Tracecat’s secret manager.

tracecat secrets delete SECRET_NAME

Schedules Management

Creating schedules

tracecat schedule create WORKFLOW_ID
ArgumentsTypeDescriptionDefaultRequired
workflow_idTEXTWorkflow IDNoneYes
OptionsShortTypeDescriptionDefault
--data-dTEXTJSON Payload to send (trigger context)None
--every-eTEXTInterval at which the schedule should runNone
--offset-oTEXTOffset from the start of the intervalNone

Listing schedules

traceat schedule list

Updating schedules

tracecat schedule update SCHEDULE_ID [OPTIONS]
ArgumentsTypeDescriptionDefaultRequired
schedule_idTEXTSchedule IDNoneYes
OptionsShortTypeDescriptionDefault
--data-dTEXTJSON Payload to send (trigger context)None
--every-eTEXTInterval at which the schedule should runNone
--offset-oTEXTOffset from the start of the intervalNone

Deleting schedules

tracecat schedule delete [SCHEDULE_ID]

Dev commands

Provides development tools for managing API interactions, generating specifications, and more.

CommandDescription
apiHit the API endpoint with an authenticated service client.
generate-specGenerate OpenAPI specification. Requires npx.
generate-udf-docsGenerate UDF documentation.
whoamiPrint the current role of the authenticated user.