Projects and access

Every command runs inside one project. The CLI shares the permissions model of the dashboard, so the same four roles and the same rules apply. Read roles and permissions for the model itself.

The active project

Set the active project by id or by name.

helios project use "engineering digests"

The CLI picks the project in this order. The first match wins.

1. The --project <id> flag on the command.
2. The HELIOS_PROJECT environment variable.
3. The project saved by helios project use.

HELIOS_PROJECT=<id> helios workflow list

helios workflow list --project <id>

After login the personal project is active. project list shows each project's role and visibility and marks the active one.

helios project list

Check who you are, which project is active, and your role in it.

helios auth whoami

Every list command respects the active project. workflow get also shows your effective role on that workflow.

Share a resource

Grant a role on any resource to a person, a group, a service account, or everyone in the org.

helios share workflow/<id> --with group:oncall --role operator

Add an expiry date.

helios share chat/<id> --with user:<id> --role viewer --expires 2026-10-01

Revoke a direct grant.

helios unshare workflow/<id> --from group:oncall

Resource types. project, workflow, chat, integration, mcp-server, db-connection, service-account.

Principals. everyone, user:<id>, group:<id or name>, sa:<id or name>.

Roles. viewer, operator, editor, admin. You cannot grant a role above your own.

Chats can only be shared as viewer, expire in one day, and cannot be shared with everyone. Service accounts can be shared as viewer or admin only. Grants to a project's default service account are refused because they could not be revoked.

Audit access

See your effective role and every grant on a resource, direct or inherited.

helios access list workflow/<id>

Pipe it for a scripted audit.

helios access list project/<id> --json

See everything others have shared with you.

helios shared list

Groups

Groups need the org admin role.

helios group create oncall --member user:<id> --member sa:deploy-bot
helios group list
helios group get oncall
helios group rename oncall on-call
helios group member add on-call user:<id>
helios group member remove on-call sa:deploy-bot
helios group delete on-call --yes

Deleting a group removes every grant it holds.

Service accounts

A service account is an identity a workflow can run as. Each project has a default account. You can also create named accounts.

helios service-account create deploy-bot
helios service-account list
helios service-account get deploy-bot

get shows which workflows use the account and what it has access to.

Make a workflow run as an account. The account needs an operator grant on the workflow first.

helios share workflow/<id> --with sa:deploy-bot --role operator
helios service-account assign deploy-bot <workflow-id>

Revert the workflow to run as its owner.

helios service-account unassign <workflow-id>

Disable an account to stop every run that uses it. Enable it to resume.

helios service-account disable deploy-bot
helios service-account enable deploy-bot

Rename or delete a named account. Deleting removes its grants.

helios service-account rename deploy-bot release-bot
helios service-account delete release-bot --yes

Errors

HTTP failures map to exit codes and print the server message. A 403 means you have no access, or the resource does not exist. The CLI does not tell these apart.