Projects

In Spiral, projects are the fundamental unit for structuring resources, access controls, and usage tracking.

Projects can be managed either through the Spiral CLI or the PySpiral client.


spiral projects --help

Creating a Project

Projects are created within an organization. Each project has a globally unique and discoverable ID that is used to identify it across the Spiral platform. You can also configure a description to provide context only to those users with permission to view the project.

To create a new project, use the Spiral CLI:


spiral projects create --name "My First Project"

Listing Projects

You can list all projects visible to you using the Spiral CLI:


spiral projects ls


                                   Projects
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ id                      ┃ organization_id                ┃ name             ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ blazing-parakeet-036267 │ org_01J9KF5Y2CB6DFK9YMBKG7S0Q4 │ My First Project │
└─────────────────────────┴────────────────────────────────┴──────────────────┘

Permissions

Projects can be shared with other users, teams, organizations etc. using grants. For more information on grants and principals, see the documentation on authorization. For more information on access across systems, see the documentation on OIDC.

You can list all grants for a project using the Spiral CLI:


spiral projects grants blazing-parakeet-036267


                                                                Project Grants
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ id                          ┃ project_id              ┃ role_id ┃ principal                                                                ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ grant_Y7DH5asdM33eMR7leXtXx │ blazing-parakeet-036267 │ admin   │ /org/org_01J9KF5Y2CB6DFK9YMBKG7S0Q4/user/user_01JAYY9RA8AR8ZCC93VJD7S71Z │
│ grant_zwZdWVcBUBluRIhHebsbG │ blazing-parakeet-036267 │ viewer  │ /org/org_01J9KF5Y2CB6DFK9YMBKG7S0Q4/role/guest                           │
│ grant_4SyXL7hRsS8jgc0eoc6KU │ blazing-parakeet-036267 │ viewer  │ /org/org_01J9KF5Y2CB6DFK9YMBKG7S0Q4/role/member                          │
│ grant_ASyW3OFWhw943e2So96ZZ │ blazing-parakeet-036267 │ admin   │ /org/org_01J9KF5Y2CB6DFK9YMBKG7S0Q4/role/owner                           │
└─────────────────────────────┴─────────────────────────┴─────────┴──────────────────────────────────────────────────────────────────────────┘

You can grant a role on a project to a user using the Spiral CLI:


spiral projects grant blazing-parakeet-036267 --role viewer --org-id org_01J9KF5Y2CB6DFK9YMBKG7S0Q4 --org-user user_01JAYY9RA8AR8ZCC93VJD7S71Z

You can grant a role on a project to all users with a specific role in an organization using the Spiral CLI:


spiral projects grant blazing-parakeet-036267 --role viewer --org-id org_01J9KF5Y2CB6DFK9YMBKG7S0Q4 --org-role member

For more details on managing grants, such as authorizing compute jobs in AWS, GCP, or Modal to access project resources, see grant command.