# CLI hooks

CLI hooks allow you to run custom scripts on scans before the final result is sent to the backend. This offers an interface to process the component data and add custom component properties. 

## Scanning with a hook script

You can place your hook script in a preferred directory/folder. Once your script is ready, you scan your repository using the `--hook-script` command line argument.

{% tabs %}
{% tab title="npm" %}

```bash
npx @omlet/cli analyze --hook-script ./path/to/hook-script.js
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn dlx @omlet/cli analyze --hook-script ./path/to/hook-script.js
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm dlx @omlet/cli analyze --hook-script ./path/to/hook-script.js
```

{% endtab %}
{% endtabs %}

### `afterScan` hook

Currently, `afterScan` is the only hook supported by Omlet CLI. This hook is executed after a scan is completed successfully.

Here is a sample hook script uses the `afterScan` hook:

{% code title="hook-script.js" %}

```javascript
module.exports = {
    async afterScan(components) {
        for (const component of components) {
            component.setMetadata("hasStories", await hasStories(component.filePath));
            component.setMetadata("hasTests", await hasTests(component.filePath));
        }
    }
}
```

{% endcode %}

{% hint style="info" %}
If you have the `@omlet/cli` package installed as a dependency, the `@type` annotation will enable auto-complete features and inline documentation for functions and components.
{% endhint %}

The `setMetadata` function can add properties to components with `string`, `number`, `date` or `boolean` values, such as:

* `Owner`: The code owner information in the CODEOWNERS file or any custom source. i.e. `@acme/design-system`, `@acme/backoffice`, `@acme/marketplace`
* `Has stories`: True or false depending on whether Storybook stories exist for a given component
* `# of props`: Number of props of each individual component

Here are a few things to know about the `afterScan` hook:

* `afterScan` hook can be defined both as an async or sync function. 
* The data passed to the hook is read-only, except the metadata that is editable with the `setMetadata` function.
* You can use npm packages as long as they're available in the Node.js runtime.

### `Component` object properties

Here are the properties of the `Component`object provided by the `afterScan` hook:

<table data-full-width="false"><thead><tr><th width="208">Property</th><th width="261">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td><code>String</code></td><td>Unique identifier for the component.</td></tr><tr><td>name</td><td><code>String</code></td><td>Name of the component as exported in the source code.</td></tr><tr><td>createdAt</td><td><code>Date</code></td><td>Creation date of the component, extracted from the git history. Optional.</td></tr><tr><td>updatedAt</td><td><code>Date</code></td><td>Last updated date of the component, extracted from the git history. Optional.</td></tr><tr><td>packageName</td><td><code>String</code></td><td>Package name the component belongs to.</td></tr><tr><td>filePath</td><td><code>String</code></td><td>File path to the component within the repository.</td></tr><tr><td>props</td><td><p><code>Array of objects</code></p><pre class="language-json"><code class="lang-json">[{
    name: String,
    defaultValue: String
}, ...]
</code></pre></td><td>List of props of the component, including name and optional default value.</td></tr><tr><td>htmlElementsUsed</td><td><code>String[]</code></td><td>List of HTML elements used within the component.</td></tr><tr><td>children</td><td><code>Component[]</code></td><td>Child components detected in the scan.</td></tr><tr><td>parents</td><td><code>Component[]</code></td><td>Parent components detected in the scan.</td></tr></tbody></table>

## Analyzing custom component properties

Once you have your custom properties on Omlet, you can create tags based on them to analyze the component usage. To learn more, check out [Component tags](/cli-and-dashboard/components/use-tags-for-custom-analyses.md) and take a look at [Create custom charts](/cli-and-dashboard/analytics/create-custom-charts.md) documentations.

<figure><img src="/files/pKora3edjqG9cIs0xOct" alt=""><figcaption></figcaption></figure>

For string-based custom properties, such as Team or Codeowner, you can directly analyze them in the charts—no need to create individual tags for their values.

<figure><img src="/files/Njxrb8Y4kqAQ8NidO9eU" alt=""><figcaption></figcaption></figure>

## Next up

Check these tutorials for popular use cases CLI hooks:

{% content-ref url="/pages/YsxSR6DkWEyrKjHlOMJY" %}
[Tutorial 1: Team/code owner usage](/cli-and-dashboard/learn-omlet-cli/custom-component-properties/tutorial-1-team-code-owner-usage.md)
{% endcontent-ref %}

{% content-ref url="/pages/8rhgn2WMrT5OwPUcjRjd" %}
[Tutorial 2: Package version tracking](/cli-and-dashboard/learn-omlet-cli/custom-component-properties/tutorial-2-package-version-tracking.md)
{% endcontent-ref %}

Here are some other examples scripts to identify components based on Test and Storybook coverage, visual elements and `@deprecated` comments:

{% content-ref url="/pages/JCbZfrcfIwQgPgbAkkmx" %}
[Other example scripts](/cli-and-dashboard/learn-omlet-cli/custom-component-properties/other-example-scripts.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.omlet.dev/cli-and-dashboard/learn-omlet-cli/custom-component-properties/cli-hooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.