squirro_asset CLI Reference

squirro_asset CLI Reference#

The squirro_asset tool manages all Squirro code artifacts, which are called custom assets. Custom assets include pipelets, dashboard widgets, dashboard loaders, dataloader plugins, Studio plugins, project templates, machine learning workflows, MLflow models, agent tools, and UI bundles.

The squirro_asset command is part of the Squirro Toolbox, which runs on Windows, macOS, and Linux. For information about downloading and installing the toolbox, see the Squirro Toolbox page.

Overview#

The first parameter is the type of asset, for example widget, pipelet, or dashboard_loader.

If you are unsure of what parameters are allowed, you can request help by adding the --help parameter.

The following output is an example. The asset types and options that your installation supports depend on the version of the Squirro Toolbox, so run the command to see the exact list.

> squirro_asset --help
usage: squirro_asset [-h] [--verbose] [--log-file LOG_FILE] [--version]
                     {type} ...

Squirro asset management tool

positional arguments:
  {type}                asset type help
    widget              Manage custom widgets
    pipelet             Manage custom pipelets
    dashboard_loader    Manage custom dashboard_loader
    dataloader_plugin   Manage custom dataloader_plugin
    studio_plugin       Manage custom studio_plugin
    project_template    Manage custom project_template
    ml_workflow_plugin  Manage custom ml_workflow_plugin
    mlflow_models       Manage custom mlflow_models
    genai_plugin        Manage custom genai_plugin
    ui_bundle           Manage custom ui_bundle

General Options:
  -h, --help            Show this help message and exit.
  --verbose, -v         Show additional information.
  --log-file LOG_FILE   Log file on disk.
  --version             show program's version number and exit

Every asset type supports the same two subcommands:

  • upload

    Packages a local folder and uploads it to the Squirro server, creating the asset or updating it if an asset of the same name already exists. The folder is passed with --folder (or -f), and the last part of that path becomes the asset name, so it must contain only alphanumeric characters, hyphens, or underscores. Uploading ./plugins/my_dashboard_loader creates an asset named my_dashboard_loader, and a folder named my dashboard loader or my.dashboard.loader is rejected.

    Files whose name starts with an underscore or a dot are not stored, wherever they sit in the folder, except __init__.py files. The upload reports no error for them, so a helper module such as _utils.py is silently left out and code that imports it fails. Name such files without the leading underscore. UI bundles are the exception and keep files whose name starts with an underscore.

  • list

    Returns all assets of that type as JSON. Each entry contains the metadata from the asset configuration file, together with the asset name, hash, directory, and a resources object listing the uploaded files grouped by file type.

Both subcommands take the same connection options: --token (or -t) for the user token and --cluster (or -c) for the cluster endpoint. Use --workspace to target a specific workspace. That option has no effect on Studio plugins and GenAI plugins, which are always installed for the whole cluster.

The pipelet type is the exception. A pipelet holds custom code that runs inside the data pipeline, so it supports additional subcommands for validating a script and for running items through it, and its upload subcommand takes the script file and a pipelet name instead of a folder. For more information, see the Pipelets section below.

Asset Configuration#

Configuration for an asset is read from a file named after the asset type inside the uploaded folder, for example studio_plugin.json or project_template.json. Those files are parsed as Hjson, so they can contain comments and trailing commas. The name and hash properties are reserved for internal use.

Most asset types also support a title property, which holds the display name that the Squirro UI shows. The asset name taken from the folder only identifies the asset, so use title when the asset needs a readable name with spaces or capitalization.

Permissions#

Uploading an asset requires a user with administrator rights. Listing assets works with any user token, but an asset configuration can restrict an asset to users holding specific permissions with a user_permissions key. Assets restricted that way are omitted from the list for users who do not hold one of those permissions, so two users can receive different results from the same list command.

Dashboard Widgets#

A custom widget extends a Squirro dashboard with a visual experience that the built-in widgets do not cover. You can use the squirro_asset tool in place of the squirro_widget tool to manage these widgets.

To upload a custom widget:

squirro_asset widget upload --folder <dashboard-widget-folder> --token <token> --cluster <cluster-url>

To list all custom widgets:

> squirro_asset widget list --token <token> --cluster <cluster-url>
[
    {
        "hash": "9a6cee78-28e5-11e6-90b4-843835563242",
        "name": "name-1",
        "title": "title-1",
        "directory": "/var/lib/squirro/topic/widgets/tenant",
        "resources": {
            "html": [
                "cells.html",
                "row.html",
                "widget.html",
                "header.html"
            ],
            "css": [
                "widget.css"
            ],
            "js": [
                "widget.js"
            ]
        }
    },
    {
        "directory": "/var/lib/squirro/topic/widgets/tenant",
        "hash": "228da928-c076-11e6-b6c3-80e65013fba6",
        "name": "name-2",
        "resources": {
        }
    }
]

For more information about building a custom widget, see the Custom Widgets page.

Dashboard Loaders#

A dashboard loader runs custom code when a dashboard loads, so that you can adjust the dashboard programmatically, for example by changing the sections that it shows.

To upload a dashboard loader:

squirro_asset dashboard_loader upload --folder <dashboard-loader-folder> --token <token> --cluster <cluster-url>

where <dashboard-loader-folder> is a directory containing the HTML, CSS, and JavaScript files of the dashboard loader, along with a dashboard_loader.json file.

To list all dashboard loaders:

> squirro_asset dashboard_loader list --token <token> --cluster <cluster-url>
[
    {
        "hash": "ec43609e-c5c6-11e6-ac8a-80e65013fba6",
        "name": "name-1",
        "title": "title-1",
        "directory": "/var/lib/squirro/topic/assets/dashboard_loader/tenant",
        "resources": {
            "css": [
                "mycss.css"
            ]
        }
    },
    {
        "directory": "/var/lib/squirro/topic/assets/dashboard_loader/tenant",
        "hash": "bed8e082-c395-11e6-94ff-000c29dfbc49",
        "name": "name-2",
        "resources": {
            "html": [
                "main.html"
            ]
        },
        "title": "title-2"
    }
]

For more information about what to write inside a dashboard loader, such as manipulating dashboard sections programmatically, see the Custom Sections API page.

Dataloader Plugins#

A dataloader plugin adds a data source to the Squirro data loader, so that you can import data from a system that the built-in plugins do not cover.

To upload a dataloader plugin:

squirro_asset dataloader_plugin upload --folder <dataloader-plugin-folder> --token <token> --cluster <cluster-url>

where <dataloader-plugin-folder> is a directory containing the following files:

  • The dataloader plugin Python file.

  • A requirements.txt file listing any external Python dependencies needed for the plugin.

  • A PNG file used as the logo for the dataloader plugin in the Squirro UI. The logo renders as a small icon, so use a square image, and keep the file small so that the list of plugins stays quick to load.

  • A dataloader_plugin.json file containing the metadata for the dataloader plugin, in Hjson format. The format is shown below.

{
    # title of the dataloader plugin to be displayed in the UI
    "title": "Hipchat",

    # description of the dataloader plugin to be displayed in the UI
    "description": "For importing data into hipchat",

    # Name of the plugin file
    "plugin_file": "hipchat.py",

    # Name of the requirements file containing the python dependencies
    "requirements_file": "requirements.txt",

    # Category under which to show this dataloader plugin, Possible options are:
    # 'web', 'socialMedia', 'import', 'developers', 'enterprise', 'businessIntelligence', 'crm', 'itsm'
    "category": "developers",

    # Name of the PNG file to be used as a thumbnail while displaying the dataloader plugin in the UI
    "thumbnail_file": "Hipchat_Atlassian_logo.png"
}

To list all dataloader plugins:

squirro_asset dataloader_plugin list --token <token> --cluster <cluster-url>

Each entry also contains a config_options list describing the configuration options that the plugin declares. Those options come from the plugin itself, not from the dataloader_plugin.json file.

For more information about writing the plugin itself, including the boilerplate, the configuration options, and the DataSource class, see the Data Loader Plugins page.

Studio Plugins#

A Studio plugin adds a custom page to the Squirro UI, for example an administration screen or a project configuration screen.

To upload a Studio plugin:

squirro_asset studio_plugin upload --folder <studio-plugin-folder> --token <token> --cluster <cluster-url>

The folder must contain a file named plugin.py, which holds the Flask application for the page. Any other file name is ignored and the plugin does not load. Next to it, add a studio_plugin.json file with the plugin metadata:

{
    "title": "Index Manager",
    "location": "server"
}

where title is the name shown in the Squirro UI and location determines where the plugin appears in the navigation:

  • load

    The Data section.

  • enrich

    The Enrich section.

  • visualize

    The Dashboards section.

  • settings

    The Settings section.

  • project_settings

    The project configuration.

  • server, cluster, and workspace

    The administration sections outside a project. On an instance that uses workspaces, cluster places the plugin in the cluster administration section, workspace places it in the workspace administration section, and server is treated as cluster. On an instance that does not use workspaces, all three values place the plugin in the server administration section.

If you omit location, the plugin has no entry in the navigation and can only be opened by its URL, which suits a plugin that only provides an API. Otherwise, use one of the values listed above, because the page of a plugin that sets any other value does not open.

The folder can also contain any files the plugin needs, such as HTML templates, a static directory with assets, a config.js file holding the client-side view for the plugin page, and a requirements.txt file listing additional Python packages. Any package listed in requirements.txt is installed on the server during the upload.

Studio plugins are installed for the whole cluster, not for a single project.

A Studio plugin can also provide tools for Squirro Neo. A function marked with the tool decorator is offered to the Neo agent automatically, without a separate upload.

To list all Studio plugins:

squirro_asset studio_plugin list --token <token> --cluster <cluster-url>

Project Templates#

A project template packages an exported Squirro project together with the metadata used in the Create Project dialog, such as a title, a description, a thumbnail, and an onboarding guide.

To upload a project template:

squirro_asset project_template upload --folder <project-template-folder> --token <token> --cluster <cluster-url>

The folder must contain an exported project in .sqproj format, the thumbnail image, and a project_template.json file with the template metadata:

{
    "title": "Cognitive Search",
    "description": "Cognitive Search Project",
    "thumbnail_file": "cognitive_search.png"
}

The squirro_project_template tool assembles that folder for you and adds the onboarding guide to the exported project.

Warning

The upload succeeds even when the folder contains no .sqproj file. The template then appears in the Create Project dialog, and the failure only surfaces when someone tries to create a project from it. After uploading a template, create a project from it once to confirm that the template is complete.

To list all project templates:

squirro_asset project_template list --token <token> --cluster <cluster-url>

For more information about producing the .sqproj export, see the Project Export & Import page. For more information about project templates in general, see the Project Templates Overview page.

ML Workflow Plugins#

An ML workflow plugin holds a machine learning workflow configuration. Squirro uses that asset type for the workflows that come with the platform, such as the default query-processing workflow, which every project receives when it is created.

To upload an ML workflow plugin:

squirro_asset ml_workflow_plugin upload --folder <ml-workflow-plugin-folder> --token <token> --cluster <cluster-url>

Important

Uploading a workflow with that command does not add the workflow to your projects, and the workflow does not become selectable in AI Studio. To build a machine learning workflow for a project, use AI Studio. For more information, see the AI Studio page.

The folder contains the workflow configuration and an ml_workflow_plugin.json file that gives the workflow a title and points to that configuration:

{
    "title": "Document Embedder: Similar Searches",
    "config_file": "config.json"
}

The file referenced by config_file holds the workflow definition itself, with its dataset and pipeline sections.

To list all ML workflow plugins:

squirro_asset ml_workflow_plugin list --token <token> --cluster <cluster-url>

For more information about the steps available in a workflow definition, see the Standard Types page.

MLflow Models#

The mlflow_models asset type stores a model directory produced by MLflow.

To upload an MLflow model:

squirro_asset mlflow_models upload --folder <mlflow-model-folder> --token <token> --cluster <cluster-url>

The folder must contain the following files, otherwise the upload is rejected:

<mlflow-model-folder>/
├── meta.yaml
└── artifacts/
    └── model/
        ├── MLmodel
        ├── conda.yaml
        ├── python_model.pkl
        └── requirements.txt

MLflow models are stored for the whole cluster rather than for a single project or workspace, so each model name must be unique across the cluster. Uploading a model under a name that already exists replaces that model.

Serving an uploaded model requires additional setup on the Squirro instance. To use one, visit the Squirro Support website and submit a technical support request.

To list all MLflow models:

squirro_asset mlflow_models list --token <token> --cluster <cluster-url>

GenAI Plugins#

A GenAI plugin adds custom tools to the Squirro agent framework, which agents can then use to answer a question or perform an action.

Note

A GenAI plugin is specific to the Squirro agent framework. Neo does not load GenAI plugins, and takes its tools through the Model Context Protocol (MCP) instead. A tool that has to reach Neo belongs either on an MCP server the platform connects to, as described on the V1 Catalog MCP Servers (preview) page, or in a Studio plugin, where a tool declared with the tool decorator is picked up automatically.

To upload a GenAI plugin:

squirro_asset genai_plugin upload --folder <genai-plugin-folder> --token <token> --cluster <cluster-url>

The folder is a Python package, so it contains an __init__.py file next to the tool implementation, and an optional requirements.txt file listing any additional Python packages. Any package listed in requirements.txt is installed on the server during the upload.

GenAI plugins are installed for the whole cluster, not for a single project.

The GenAI service loads plugins when it starts, so restart that service after every upload. Until the restart, the new or updated tool is not available. The command depends on how your instance is deployed, so if you are unsure, visit the Squirro Support website and submit a technical support request.

To list all GenAI plugins:

squirro_asset genai_plugin list --token <token> --cluster <cluster-url>

For a complete walkthrough, including the code of a custom tool, see the Developing Custom Tools page.

UI Bundles#

A UI bundle is a compiled JavaScript application that allows you to deploy custom frontend extensions to a Squirro instance at runtime, without rebuilding the platform. The UI bundles use Module Federation, a pattern in which a host application loads independently built and deployed JavaScript modules at runtime.

The bundle must contain a dist/mf-manifest.json file. Any node_modules directory in the bundle folder is ignored on upload.

To upload a UI bundle:

squirro_asset ui_bundle upload --folder <ui-bundle-folder> --token <token> --cluster <cluster-url>

To list all UI bundles:

squirro_asset ui_bundle list --token <token> --cluster <cluster-url>

For a step-by-step guide on building and deploying a UI bundle, see the Developer Guide page.

Pipelets#

A pipelet is a custom processing step that runs inside the data pipeline. You can use the squirro_asset tool in place of the pipelet tool to manage pipelets. Instead of

pipelet <any options>

you can use squirro_asset followed by pipelet as an asset type, like so:

squirro_asset pipelet <any options used for the pipelet tool>

Use the --help option to obtain detailed help on the squirro_asset pipelet commands and options.

The following output is an example. The subcommands and options that your installation supports depend on the version of the Squirro Toolbox, so run the command to see the exact list.

> squirro_asset pipelet --help
usage: squirro_asset pipelet [-h]
                             {validate,consume,rerun,upload,source,list} ...

positional arguments:
  {validate,consume,rerun,upload,source,list}
                        sub-command help
    validate            Validates that the script doesn't violate any
                        restrictions
    consume             Runs one or more items through the consume method of
                        the pipelet
    rerun               Re-runs a pipelet on the server
    upload              Uploads the script to Squirro
    source              Creates a source that is configured with `name`
    list                List all available pipelets

options:
  -h, --help            show this help message and exit

For more information about pipelets, see the Pipelets page.

Deleting an Asset#

The squirro_asset tool cannot remove an asset. To delete one, use the delete_asset method of the Python SDK, which also requires a user with administrator rights:

client.delete_asset(asset_type="dashboard_loader", name="layer_loader")

For assets that are installed for the whole cluster, such as Studio plugins and GenAI plugins, pass global_asset=True.

Pipelets are the exception. For a pipelet, delete_asset fails with a 404 error and the pipelet stays in place, so use the delete_pipelet method instead:

client.delete_pipelet("my_pipelet")

For more information, see the SquirroClient (Python SDK) page.


Contents
This page
View as Markdown