> ## 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.

# Paths and core concepts

> Address workspaces, projects, directories, and assets with aspect:// URLs, use IDs, and choose a default workspace.

Aspect paths follow the same hierarchy you see in the app:

```text theme={null}
aspect://<workspace>/<project>/<folders>/<file>
```

A **workspace** holds your team's projects. A **project** holds folders and assets. A **directory** is a folder, and an **asset** is a file. A project is also the boundary for a mounted volume; you can mount its root or a folder within it.

## Browse from the top

```bash theme={null}
aspect ls
aspect ls "aspect://Acme/"
aspect ls "aspect://Acme/Documentary/"
aspect ls "aspect://Acme/Documentary/Footage/"
aspect ls "aspect://Acme/Documentary/Footage/interview.mov"
```

These commands list workspaces, projects, a project's contents, a folder's contents, and one file respectively. `ls` lists one level at a time. Add `--json` to get entries with their IDs and types.

| Path | Refers to |
| - | - |
| `aspect://` | All workspaces you can access |
| `aspect://Acme` | The Acme workspace |
| `aspect://Acme/Documentary` | A project |
| `aspect://Acme/Documentary/Footage` | A folder in that project |
| `aspect://Acme/Documentary/Footage/interview.mov` | One asset |

## Names, spaces, and IDs

Names are matched case-insensitively within their parent. Quote the whole URL so spaces and shell characters remain part of the path:

```bash theme={null}
aspect ls "aspect://Acme Post/Brand Film/Day 01"
```

Each segment can also be the resource's UUID. If a name matches more than one resource, the CLI returns `ambiguous_name` and candidate IDs. Replace the ambiguous segment with its ID; obtain IDs from `aspect ls --json` or `aspect workspace list --json`.

URL-encoded segments are accepted. A slash that is part of a name must be encoded as `%2F`, because an ordinary `/` separates path levels. An Aspect web or share link is not an `aspect://` path.

## Set a default workspace

```bash theme={null}
aspect workspace list
aspect workspace use "Acme"
aspect ls "aspect://~/Documentary"
```

`workspace use` saves a default on this computer. The `~` in the **workspace position** resolves in this order:

1. The `ASPECT_WORKSPACE` environment variable, if set to a workspace name or ID.
2. Your saved default workspace, if it is still accessible.
3. Your only workspace, if you belong to exactly one.

If no default can be selected, the CLI asks you to name a workspace. Explicit workspace URLs are useful in scripts because they do not depend on saved defaults.

## Mounts, downloads, and pins

| Operation | What you get |
| - | - |
| [Mount](/docs/cli/mounts) | A volume backed by your Aspect project. Applications fetch file data as they read it, and writes are uploaded in the background. |
| [Download](/docs/cli/downloads) | An ordinary local copy. Later edits to that copy are not automatically uploaded. |
| [Pin](/docs/cli/cache-and-offline) | Files kept locally for offline access through a mount. Wait for pin synchronization before disconnecting. |
| [Retrieve a proxy](/docs/cli/proxies) | A generated viewing copy, downloaded separately from the original. |

Collections curate files without changing their underlying project paths. Use the app or [MCP server](/docs/api-reference/mcp) to work with collections, then address files by their project and folder paths in the CLI.

Commands use the permissions of the signed-in account or API key owner. Knowing a path or an ID does not grant access to it.