> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache and offline files

> Control local cache usage, pin complete files for offline access, and confirm synchronization before going offline.

Aspect keeps file content locally in two ways. The **cache** holds data fetched as you work and can evict it to free space. **Pins** keep selected files available locally for offline use through a mount.

Opening a file once does not guarantee that all of it is cached or will remain available offline. Pin the files you need and wait for synchronization.

## Prepare an offline session

<Steps>
  <Step title="Mount while connected">
    ```bash theme={null}
    aspect mount "aspect://Acme/Documentary"
    ```

    A new CLI mount resolves its path through Aspect's API. Create the mount while online rather than relying on a pin to make a later mount command work without a connection.
  </Step>

  <Step title="Pin the files you need">
    ```bash theme={null}
    aspect pin add "aspect://Acme/Documentary/Footage"
    ```

    The target can be a project, directory, or individual asset. The command registers the pin; its return does not mean downloading has finished. Adding the same pin again returns the existing pin.
  </Step>

  <Step title="Wait for the pin to finish">
    ```bash theme={null}
    aspect pin list
    aspect pin list --json
    ```

    Confirm that the needed pins show `synced`, and that their downloaded content is complete. Check errors or storage limits before leaving the network.
  </Step>

  <Step title="Keep the mount available">
    Work through the existing mount. [Check for pending or failed uploads](/docs/cli/mounts#finish-work-and-unmount) before disconnecting, and let Aspect synchronize changes after reconnecting.
  </Step>
</Steps>

## Pin states

| State | Meaning and next step |
| - | - |
| `fetching_metadata` | Aspect is finding the files included in the pin. Wait. |
| `downloading_chunks` | Content is still downloading. Keep the computer online. |
| `synced` | The pin has synchronized. |
| `error` | Synchronization failed. Inspect the reported error and your connection. |
| `over_limit` | The pin exceeds available pin storage. Remove unneeded pins or increase the limit. |

`aspect status` also includes an overall pin sync summary. For an offline session, inspect the specific pins you need rather than relying only on an aggregate byte count.

## Set storage limits

```bash theme={null}
aspect settings list
aspect settings set cache-limit 200GB
aspect settings set pin-limit 500GB
```

These settings apply to Aspect on this computer, including the shared filesystem service when you use the desktop app.

| Setting | Controls | Minimum |
| - | - | - |
| `cache-limit` | Storage for content cached as you open it | `10GB` |
| `pin-limit` | Storage for pinned offline content | `5GB`, and not below content already pinned |

Sizes require a unit: `B`, `KB`, `MB`, `GB`, or `TB`. They are decimal units; fractional sizes such as `1.5TB` are accepted. `aspect settings list --json` reports values in bytes. Choose limits that leave room for your other files and applications.

## Remove a pin

```bash theme={null}
aspect pin remove "aspect://Acme/Documentary/Footage"
```

You can also pass a pin ID from `aspect pin list --json`.

Removing a pin removes the offline-retention requirement. It does not delete files from Aspect, and cached content may remain on disk until the cache evicts it.

A file included only through a pinned parent folder does not have its own pin to remove. If `pin remove` reports `not_pinned` for that file, remove the parent's pin instead. Pin smaller folders or individual assets when you need finer control.

For a local copy that you manage independently of mounted-drive caching, use [download](/docs/cli/downloads).