Main Commands

This page covers the Squirro CLI command groups you use most. Squirro CLI is designed to be driven by an AI coding assistant, so treat these commands as a reference for following along, checking a result, or investigating a failure rather than as a list to work through by hand. For more information, see the Squirro CLI page.

For the authoritative list on the build you have installed, run the squirro --help command, or squirro <group> --help for a single group, where <group> is one of the names that squirro --help lists, such as config or profile. Adding a subcommand reaches the level where the options are documented.

# Ask a subcommand which options it accepts
squirro config apply --help

# Output of the command above: every option, with its default where it has one
Usage: squirro config apply [OPTIONS] [TARGET]

  Apply configuration from file(s).

Options:
  --dry-run                       Show what would be done without applying
  --yes                           Skip interactive confirmation prompts
  --apply-by-name / --no-apply-by-name
                                  Match records by name instead of id (for
                                  cross-environment applies). Defaults to on
                                  for mirror profiles. Raises an error if
                                  duplicate names are found.
  --allow-deletion                Allow deletion of server resources that are
                                  absent from local config. Off by default to
                                  prevent accidental data loss.
  --force                         Override apply-time safety guards (model-
                                  level overwrite/conflict protection). Use
                                  with care.
  --help                          Show this message and exit.

Global Options

Global options belong to the top-level squirro command, so they go before the subcommand.

• squirro --profile dev config pull

  Correct. A global option comes before the subcommand.

• squirro config pull --profile dev

  Wrong. The command reports No such option.

The available global options are:

• --profile

  Use a named profile for this command instead of the default one.

• --project-id

  Use a different Squirro project than the one the profile maps for this command.

• --cluster and --token

  Override the cluster URL and the authentication token. Only squirro connection and squirro load read these. Every other command builds its connection from the active profile, so the override is ignored without a warning. To reach a different instance, switch profile instead.

• -v or --verbose

  Add detail to the output. Repeat as -vv for debug output.

• -q or --quiet

  Commands print the same output with or without this flag. To silence a command, discard its output with > /dev/null 2>&1.

Warning

Global options otherwise go before the subcommand, but squirro project create and squirro project list read --profile only when it comes after the subcommand. Placed before, the option is ignored without any warning and both commands fall back to the default profile, so a create registers the project in the wrong profile.

• squirro project create <folder> <id> --profile prod

  Correct, because the flag follows the subcommand.

• squirro --profile prod project create <folder> <id>

  Wrong, because the flag is ignored and prod is never used.

Profiles and Projects

A profile describes one instance: its cluster URL, its credentials, and the mapping from project directory names to project identifiers on that instance.

• squirro profile create prod

  Create a profile, asking for what it needs.

• squirro profile create prod --user

  Create it in ~/.squirro instead, so it is visible from any directory.

• squirro profile list

  List the profiles visible from here.

• squirro profile show prod

  Show one profile in detail.

• squirro profile use dev

  Set the default profile.

• squirro connection

  Test every platform in the active profile.

Registering a further Squirro project against a profile creates its project directory and adds the mapping.

# The directory name comes first, then the identifier of the project on the instance
squirro project create competitor_watch qN4rEbYlTPu1kVzFmH9dSg

# Output of the command above: the profile at the end is where the mapping landed
Created project 'competitor_watch' (qN4rEbYlTPu1kVzFmH9dSg) in profile 'dev'

That is worth reading, because project create ignores a --profile placed before the subcommand and falls back to the default.

Listing them back shows every project directory the active profile maps, with the identifier each one points at on that instance.

# List every project the active profile maps
squirro project list

# Output of the command above: each project directory, with the identifier it points at
Projects in profile 'dev':
  competitor_watch      qN4rEbYlTPu1kVzFmH9dSg
  market_intelligence   Xt7cLdWvQTaHy2ZnKpR6Bw

Run squirro connection after any credential change. It exercises every platform in the active profile and reports which ones respond.

Configuration Management

The configuration commands are the core of the tool. They move configuration between the tracked files and the instance, in both directions.

• squirro config pull

  Download the current instance configuration.

• squirro config apply --dry-run

  Show the changes an apply would make.

• squirro config apply

  Apply the local files to the instance.

• squirro config validate

  The same preview, with the record-matching and deletion options of apply.

• squirro config list

  List every supported configuration type and its path.

• squirro config schema genai/groups.json

  Show the JSON schema for one file.

Both pull and apply accept a path, which selects one configuration type rather than one file.

• squirro config pull projects/market_intelligence/platform/theme.json

  Pull the project settings of every project the profile maps, not only market_intelligence.

• squirro config apply projects/market_intelligence/enrichments/workflows.json

  Apply the pipeline workflows of every project the profile maps.

Warning

A path that names one project does not restrict the command to it. The path chooses the configuration type, and the command then runs over every project directory the active profile maps, without reporting that it did so. To work on a single project, narrow the profile itself with squirro profile use <profile> --project <folder>, or pass the global --project-id.

Pass the path to config schema exactly as squirro config list prints it. Project-level entries carry a {ProjectsConfig} template segment standing for the project directory, and wildcard paths contain an asterisk, so quote either form.

• squirro config schema 'projects/{ProjectsConfig}/platform/info.json'

  Quote a path carrying a template segment.

• squirro config schema 'projects/{ProjectsConfig}/connectors/sources/*.json'

  Quote a wildcard path as well, and give it in full. A shortened form such as connectors/sources/*.json reports that no configuration model was found.

Important

Pull before you edit, not before you apply. config apply compares your local files against the live instance, so it needs no pull beforehand, and pulling at that point would overwrite the very edits you are about to push. Mirror profiles are the exception, because for them the tracked files are the source of truth. For more information, see the Mirror Profiles page.

The everyday cycle on the profile you author on is:

1. Run squirro config pull to start from the current instance state.

2. Edit the JSON files, using squirro config schema to check field names and valid values.

3. Run squirro config apply --dry-run to review the difference.

4. Run squirro config apply to push the change.

Record Identifiers

A record is one entry inside a configuration file that maps to a single object on the instance. One workflows.json file holds several pipeline workflows, for example, and each of those is a record.

Pipeline workflows and data sources carry an id field that anchors the local record to the one on the instance. A pull fills it in, and an apply uses it to decide whether a record is new or an update.

• Leave "id": null for a record you are creating locally. The apply creates it on the instance and writes the assigned identifier back into the file, so the next apply updates that record instead of creating a second one.

• Rename freely. Because matching goes by identifier, changing the name of a record is applied as an update rather than as a deletion followed by an addition.

• Never copy an identifier between environments. Each one is valid only on the instance it came from. To apply the same file to another instance, use --apply-by-name or a mirror profile. For more information, see the Mirror Profiles page.

Apply Options

• --dry-run

  Show the difference and stop. Nothing reaches the instance.

• --yes

  Skip the confirmation prompts, for use in automation.

• --apply-by-name

  Match records by name instead of by identifier, for applying one set of files to an instance whose identifiers differ. On by default for mirror profiles. Duplicate names on the target raise an error rather than a guess.

• --allow-deletion

  Permit deletion of instance resources that are absent from the local files. Off by default, so an apply otherwise skips those resources and reports how to include them. Pass it only when you intend to remove the resources permanently.

• --force

  Override the apply-time safety guards that protect against overwriting or conflicting changes. Use it only when you know why a guard fired.

Note

There is no config diff command. Use squirro config apply --dry-run, or squirro config validate, to compare the local files against the instance.

API Access

The api group exposes every method of the Squirro Python client, and raw HTTP access, with authentication taken from the active profile.

• squirro api list topic

  Browse the methods of one service.

• squirro api help get_project

  Show the parameters of one method.

• squirro api call get_project --project-id Xt7cLdWvQTaHy2ZnKpR6Bw

  Call a method, passing its parameters as options.

• squirro api http GET https://dev.squirro.example.com/api/user/v0/<tenant>/users/<user-id>

  Make a raw HTTP request.

Method parameters are passed as options, for example --source-id Ln5wKdQzRe6TvBhX2mYcPa.

Important

api call stops reading options once it reaches the method name, so anything after it is treated as a method parameter. Put --project-id before api, as in squirro --project-id <id> api call get_project, and --format between call and the method name, as in squirro api call --format table get_project. Passing either after the method name is silently ignored. --format accepts json, pretty, table, csv, and text.

api http takes a full URL rather than a path. A bare path such as /api/v0/users/me fails with No scheme supplied.

Search

• squirro search query 'revenue growth' --count 10

  Run a query and limit the number of results.

• squirro search query 'revenue' --facets '{"language": ["en"]}' --sort 'created_at:desc'

  Filter by facet and sort the results.

• squirro search analyze 'revenue AND growth'

  Show how the query is processed.

• squirro search tokenize 'Revenue growth 2026'

  Show how the text is indexed.

analyze and tokenize are the two to reach for when a query returns something unexpected, because they show what the platform makes of your input before any results are involved.

Chat

• squirro chat agents

  List the agents available in the project, each with its name and its identifier.

• squirro chat send 'Summarize last quarter' --agent market-analyst

  Send a single message and exit.

• squirro chat interactive --agent market-analyst

  Open an interactive session.

--agent matches on the agent name, not on its identifier, so run squirro chat agents first and pass the value from the Name column. An identifier reports that the agent was not found. send answers a single message and exits, which makes it the one to use in a script. Both accept --streaming for incremental output and --context for additional JSON context.

Loading Local Data

squirro load uploads a local file to a file-based source and runs it, so the source plugin parses the file on the instance rather than locally.

• squirro load data.csv --source-id Ln5wKdQzRe6TvBhX2mYcPa --dry-run

  Preview the load without uploading anything.

• squirro load data.csv --source-id Ln5wKdQzRe6TvBhX2mYcPa --wait --yes

  Load the file and wait for the run to finish.

Warning

Loading adds the contents of the file to the source and keeps the existing items, because the platform offers no way to delete the data of a source. Where the source has deduplication turned off, loading a file it has already ingested adds a second copy of every item.

The run is asynchronous by default: the command submits it and returns. Pass --wait to block until it finishes and get a pass or fail exit code, with --timeout to change the 600-second limit. load asks for confirmation before it uploads anything, so a scripted run needs --yes as well, or it stops at the prompt without loading.

To create a new file-based source, define it in the configuration and run squirro config apply, then load the file into it.

Logs

The logs group reads the instance log files. The time and level filters are applied on the instance, so the output arrives already narrowed.

• squirro logs list

  List the available log names.

• squirro logs get --log-name topic --level error --lines 50

  Show the last 50 error-level entries of one log.

• squirro logs get --log-name topic --from '2026-09-08 14:00' --to '2026-09-08 15:00'

  Show one log over a given time range.

Secrets

The secret group stores credentials for the active profile outside the tracked files.

• squirro secret set-secret sharepoint_password '<password>'

  Store a credential outside the tracked files.

• squirro secret list-secrets

  Report the credential status of each platform in the profile.

A configuration file then refers to a stored value as ${secrets.<key>}. For how the layering works, see the Configuration Directory page.

Warning

set-secret takes the credential as a command line argument, and offers no way to supply it otherwise, so the value reaches your shell history and is visible in the process list while the command runs. Prefer keeping the credential off the command line altogether: write it into the .local.json override file, or reference it as a 1Password entry or an environment variable. For more information, see the Configuration Directory page.

Note

list-secrets reports the credential fields of each platform in the profile as Set or Placeholder, rather than listing the keys you stored with set-secret. squirro secret get, squirro secret delete, and squirro secret status are not implemented and report so when run. Use squirro profile show to review credential status.

Custom User Interface

squirro ui forwards to the Neo extensions CLI, which scaffolds, builds, and deploys a custom user interface bundle. That tool ships inside the Squirro CLI image together with the Node runtime it needs, so there is nothing extra to install, and Squirro CLI passes the credentials of the active profile through to it. Run squirro ui without arguments to see the commands it accepts, because squirro ui --help is not understood by the tool it forwards to.

For the full command set and the concepts behind bundles, see the CLI Reference page.

Groups with Limited Coverage

Two groups appear in squirro --help with less behind them than their names suggest, so ignore both until a later build:

• squirro permissions has no subcommands at all. Manage access through genai/groups.json and the project members file instead.

• squirro test offers one subcommand, squirro test config, which reports that it is not implemented rather than validating anything. Use squirro config validate instead.

Next Steps

To keep one set of tracked files and replicate it to a second and third environment, see the Mirror Profiles page. For prompts covering common delivery tasks, see the Prompt Library page.