> For the complete documentation index, see [llms.txt](https://docs.neuroinfodb.org/squirrel/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuroinfodb.org/squirrel/getting-started/squirrel-utilities.md).

# squirrel utilities

The squirrel command line program

The squirrel command line program converts DICOM and BIDS data to squirrel, displays and browses the contents of packages, and modifies, merges, extracts from, and validates existing packages.

## Installing squirrel utilities

Download squirrel from <https://github.com/gbook/squirrel/releases>

{% tabs %}
{% tab title="RHEL/Rocky/CentOS" %}

```bash
sudo yum localinstall --nogpgcheck squirrel-xxx.xx.xxx-1.elx.x86_64.rpm
```

{% endtab %}

{% tab title="Ubuntu/Debian" %}

```bash
sudo apt install p7zip # p7zip required by squirrel
sudo dpkg -i squirrel_xxxx.xx.xxx.deb
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Too many open files error**

If you encounter an error "too many open files", or you are unable to write squirrel packages, try increasing the open files limit within Linux

```bash
# increase open file limit (temporarily for the current session)
ulimit -n 2048

# increase open file limit (permanently)
# append these lines to /etc/security/limits.conf
*               soft    nofile            2048
*               hard    nofile            2048
```

{% endhint %}

## Command line usage

```bash
squirrel <tool> [options]
```

Run `squirrel <tool> --help` to see the options for a tool, and `squirrel --version` to see the installed version. There are 7 tools available

| Tool                                                                 | Description                                                                                           |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [convert](/squirrel/getting-started/squirrel-utilities/convert.md)   | Convert DICOM or BIDS data into a squirrel package                                                    |
| [info](/squirrel/getting-started/squirrel-utilities/info.md)         | Display information about a package or its contents. This is the tool to use to view non-imaging data |
| [explore](/squirrel/getting-started/squirrel-utilities/explore.md)   | Interactively browse a package in a shell                                                             |
| [modify](/squirrel/getting-started/squirrel-utilities/modify.md)     | Add, remove, or update objects within a package                                                       |
| [merge](/squirrel/getting-started/squirrel-utilities/merge.md)       | Merge two or more packages into one                                                                   |
| [extract](/squirrel/getting-started/squirrel-utilities/extract.md)   | Extract a copy of objects from a package into a directory                                             |
| [validate](/squirrel/getting-started/squirrel-utilities/validate.md) | Check if a package is valid                                                                           |

## Quick examples

### Convert DICOM to squirrel

```bash
# Default DICOM to squirrel conversion
squirrel convert /path/to/dicoms outPackage.sqrl --inputformat dicom

# Specify the output data format
squirrel convert /path/to/dicoms outPackage.sqrl --inputformat dicom --dataformat nifti4dgz

# Specify the package directory format
squirrel convert /path/to/dicoms outPackage.sqrl --inputformat dicom --dirformat seq
```

### Convert BIDS to squirrel

```bash
squirrel convert /path/to/bids outPackage.sqrl --inputformat bids
```

### Modify an existing squirrel package

```bash
# add a subject to a package
squirrel modify /path/to/package.sqrl --operation add --object subject --objectdata 'SubjectID=S1234ABC&DateOfBirth=1999-12-31&Sex=M&Gender=M'

# remove a study (remove study 1 from subject S1234ABC)
squirrel modify /path/to/package.sqrl --operation remove --object study --subjectid S1234ABC --objectid 1
```

### List information about a squirrel package

```bash
# show the package summary
squirrel info /path/to/package.sqrl

# list subject IDs
squirrel info /path/to/package.sqrl --object subject --dataset id

# list studies for a specific subject
squirrel info /path/to/package.sqrl --object study --subjectid S1234ABC

# list all subjects in CSV format
squirrel info /path/to/package.sqrl --object subject --format csv > subjects.csv
```

### Browse a package interactively

```bash
squirrel explore /path/to/package.sqrl
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.neuroinfodb.org/squirrel/getting-started/squirrel-utilities.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.