Skip to main content
Aspect paths follow the same hierarchy you see in the app:
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

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.

​
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:
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

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

Collections curate files without changing their underlying project paths. Use the app or MCP server 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.