Command Line Interface

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]

Option	Shortcut	Parameter	Description	Default
`--title`	`-t`	TEXT	Title of the workflow.	None
`--description`	`-d`	TEXT	Description of the workflow.	None
`--activate`			Activate the workflow immediately after creation.
`--webhook`			Activate the webhook for the workflow.
`--commit`	`-c`	PATH	Create 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]

Option	Shortcut	Parameter	Description	Default
`--file`	`-f`	PATH	Path 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

Option	Shortcut	Description	Default
`--webhook`		Activate its webhook as well.
`--help`		Show help message and exit.

Running a Workflow

tracecat workflow run WORKFLOW_ID [OPTIONS]

Option	Shortcut	Description	Default
`--data`	`-d`	JSON Payload to send.	None
`--proxy`		If set, run the workflow through the external-facing webhook.
`--test`		If 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

Option	Shortcut	Description	Default
`--table`	`-t`	Display 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

Argument	Type	Description	Default	Required
`secret_name`	TEXT	Secret name, can include multiple key-value pairs.	None	Yes
`keyvalues`	KEYVALUES…	Space-separated KEY-VALUE items, e.g., `KEY1=VAL1 KEY2=VAL2 ...`.	None	Yes

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

Arguments	Type	Description	Default	Required
`workflow_id`	TEXT	Workflow ID	None	Yes

Options	Short	Type	Description	Default
`--data`	`-d`	TEXT	JSON Payload to send (trigger context)	None
`--every`	`-e`	TEXT	Interval at which the schedule should run	None
`--offset`	`-o`	TEXT	Offset from the start of the interval	None

Listing schedules

traceat schedule list

Updating schedules

tracecat schedule update SCHEDULE_ID [OPTIONS]

Arguments	Type	Description	Default	Required
`schedule_id`	TEXT	Schedule ID	None	Yes

Options	Short	Type	Description	Default
`--data`	`-d`	TEXT	JSON Payload to send (trigger context)	None
`--every`	`-e`	TEXT	Interval at which the schedule should run	None
`--offset`	`-o`	TEXT	Offset from the start of the interval	None

Deleting schedules

tracecat schedule delete [SCHEDULE_ID]

Dev commands

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

Command	Description
`api`	Hit the API endpoint with an authenticated service client.
`generate-spec`	Generate OpenAPI specification. Requires npx.
`generate-udf-docs`	Generate UDF documentation.
`whoami`	Print the current role of the authenticated user.

Getting Started

Self-Hosting

Core Features

Developer Features

Command Line Interface

Installation

pipx

Workflow Management

Listing Workflows

Creating a Workflow

Committing changes to a Workflow

Activating a Workflow

Running a Workflow

Inspecting a Workflow

Viewing Workflow Cases

Deleting Workflows

Secrets Management

Creating Secrets

Listing Secrets

Deleting Secrets

Schedules Management

Creating schedules

Listing schedules

Updating schedules

Deleting schedules

Dev commands

Getting Started

Self-Hosting

Core Features

Developer Features

​Installation

​pipx

​Workflow Management

​Listing Workflows

​Creating a Workflow

​Committing changes to a Workflow

​Activating a Workflow

​Running a Workflow

​Inspecting a Workflow

​Viewing Workflow Cases

​Deleting Workflows

​Secrets Management

​Creating Secrets

​Listing Secrets

​Deleting Secrets

​Schedules Management

​Creating schedules

​Listing schedules

​Updating schedules

​Deleting schedules

​Dev commands

Installation

pipx

Workflow Management

Listing Workflows

Creating a Workflow

Committing changes to a Workflow

Activating a Workflow

Running a Workflow

Inspecting a Workflow

Viewing Workflow Cases

Deleting Workflows

Secrets Management

Creating Secrets

Listing Secrets

Deleting Secrets

Schedules Management

Creating schedules

Listing schedules

Updating schedules

Deleting schedules

Dev commands