# 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](index.md#squirro-cli) page. For the authoritative list on the build you have installed, run the `squirro --help` command, or `squirro --help` for a single group, where `` 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. ```bash # Ask a subcommand which options it accepts squirro config apply --help ``` ```bash # 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 --profile prod` > > > > Correct, because the flag follows the subcommand. > - `squirro --profile prod project create ` > > > > 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. ```bash # The directory name comes first, then the identifier of the project on the instance squirro project create competitor_watch qN4rEbYlTPu1kVzFmH9dSg ``` ```bash # 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. ```bash # List every project the active profile maps squirro project list ``` ```bash # 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 --project `, 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](mirror-profiles.md#squirro-cli-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](mirror-profiles.md#squirro-cli-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//users/` 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 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 ''` 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.}`. For how the layering works, see the [Configuration Directory](configuration-directory.md#squirro-cli-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](configuration-directory.md#squirro-cli-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](../neo/dev-guide/cli-reference.md#neo-extensions-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](mirror-profiles.md#squirro-cli-mirror-profiles) page. For prompts covering common delivery tasks, see the [Prompt Library](prompt-library.md#squirro-cli-prompt-library) page.