Authenticate and select a workspace

Sign in as yourself, pick one workspace you are granted, and check the result before you deploy or run anything. Most people do this once per machine.

At a glance

• tanomis login is a browser device flow for a person; the CLI stores the login in a named context.
• A workspace is one organization and one tenant you are granted. tanomis workspace use selects it; tanomis workspace show proves it.
• The server re-checks membership and grants on every request. Selecting never widens access.
• Pipelines and backends use an automation client, never this login.

Backend boundary: This login belongs to the person using the CLI. Do not read the CLI credential store from application code, copy its refreshable credentials into a service, or use platform-service or agent machine credentials. Pipelines and backends use an organization-owned automation client; see Automation credentials.

The complete path is:

Hosted API -> named CLI context -> signed-in person -> granted workspace -> tenant-scoped request

The first three choices are local request context. The server still verifies the credential, organization membership, tenant grant, and required operation on every request.

1. Sign in to a named context

Terminal

tanomis login --console https://api.tanomis.com --name saas

tanomis reads the public environment configuration from the hosted API, so it discovers the API origin and OIDC settings rather than relying on copied values. Device authorization is the hosted default: the CLI prints a verification address and a short code, you sign in and approve in a browser as yourself, and the CLI stores short-lived access and refreshable login state for the saas context. A device flow can start on a headless terminal, but it is not unattended: a person must finish the browser step. Do not automate it as a service credential.

Terminal

tanomis auth status
tanomis config current-context

auth status shows the context, authentication mode, API target, login state, and token expiry, never the token itself. A normal result names saas and reports logged-in: yes. Tokens are short-lived; tanomis refreshes them before a command, and if the refresh grant is gone it stops and asks you to tanomis login again.

2. Understand context versus workspace

A context chooses an environment and its local authentication configuration. A workspace chooses one organization and attached tenant from the projections granted to the signed-in person.

A request resolves selections first, then operates on tenant-scoped resources

CLI contextlocal selection

uses credentials for

Authenticated principalidentity

selects

Selected workspacederived projection

OrganizationIdentity and administration

+

TenantRuntime and data isolation

Inside the selected tenant

1. AgentStable deployment identity
2. VersionImmutable build and manifest
3. EnablementTenant traffic assignment
4. SessionTenant-scoped execution context
5. RunOne admitted unit of work

Files and interactions belong to the session; the run is one unit of work inside it.

Object	What it selects	What it cannot do
CLI context	One API environment and its login state	Grant organization or tenant access
Authenticated principal	The person whose authority bounds the request	Borrow another member’s role
Selected workspace	One granted organization, tenant, role, and capability set	Create, attach, or reassign a tenant
Tenant	The runtime and data-isolation boundary	Expand the caller’s credential or membership

Use another configured context as the default, or target it for one command:

Terminal

tanomis config use-context staging
tanomis config current-context
tanomis workspace ls --context staging

Login and workspace selection are stored per context, so switching context can change the API environment, the cached login, and the selected workspace together. Check both before a consequential command. The current CLI does not display the account identity behind a cached login; to establish it again, log out and log in as the intended account.

3. Discover your granted workspaces

Terminal

tanomis config use-context saas
tanomis workspace ls

ORGANIZATION  DISPLAY NAME  ROLE       TENANT                  STATE  DEFAULT  CAPABILITIES
northwind     Northwind     developer  bluewater-bank         ready  *        run,view
northwind     Northwind     developer  northwind-sandbox      ready           deploy,run,view

The list contains only organizations you belong to and only tenants granted to you. Capabilities summarize what you may do in each:

Capability	What it allows
view	Inspect permitted resources
run	Create sessions and run enabled agents
deploy	Deploy or change agent versions where the command permits it
manage	Govern supported connector configuration when separately enabled; it does not grant organization or tenant administration

Select a tenant whose STATE is ready. Discovery can include an attachment that is still being provisioned, and the CLI can save that selection, but the server refuses tenant-scoped operations until the attachment becomes ready.

The table is discovery, not a permanent authorization snapshot. Memberships and grants can change, and the server re-resolves them when each request arrives. workspace use also saves the displayed capabilities as a local advisory snapshot, so deploy and run commands may deny early when it lacks their capability. After an owner changes a grant, repeat workspace use and workspace show.

4. Select and verify one projection

Terminal

tanomis workspace use northwind --tenant northwind-sandbox
tanomis workspace show

context:       saas
organization:  northwind
tenant:        northwind-sandbox
role:          developer
capabilities:  deploy, run, view

If the organization has one tenant, or exactly one default, you may omit --tenant. With several tenants and no single default, the CLI refuses to guess and asks for --tenant. It also rejects an organization or tenant that was not returned by discovery.

The selected tenant becomes the command’s effective tenant, so omit a redundant --tenant flag. Deploy and session-run commands refuse an explicit tenant that differs from the selected workspace; do not assume every other command has that local conflict check.

5. Use the workspace, then clean up deliberately

Terminal

tanomis agent ls

For a first deploy and managed run, follow the Quickstart. Its commands name a tenant explicitly; when a workspace is selected, an explicit --tenant must exactly match the tenant from workspace show, and you can simply omit it.

Terminal

tanomis workspace clear
tanomis logout

workspace clear removes the local organization and tenant choice from the context and nothing on the server. logout clears the cached login and keeps the context; authenticated commands stop until you log in again. Deleting a context is a separate action that also clears its credentials.

Troubleshoot authentication and selection

What you observe	Meaning	Next action
not logged in: run tanomis login	The context has no usable access or refresh state.	Run tanomis login --name CONTEXT, or repeat --console to refresh its configuration.
Refresh fails	The refresh grant is no longer usable or the identity provider is unavailable.	Retry only for a transient outage; otherwise log in again.
no workspaces	Authentication succeeded, but this person has no active organization membership.	Ask an organization owner to confirm membership.
An organization row shows tenant (none)	Membership exists, but this person has no attached tenant they may access.	Ask an owner to confirm the attachment and, for a developer or viewer, the grant.
The organization has several tenants and no single default	There is no unambiguous tenant choice.	Repeat tanomis workspace use ORG_SLUG --tenant TENANT_ID with a tenant from workspace ls.
The selected tenant’s state is not ready	Its attachment is still provisioning.	Wait for it to be ready, then select and verify again.
The workspace lacks deploy, run, view, or manage	The projection or saved snapshot does not include the operation family.	Ask an owner to grant it, then repeat workspace use and workspace show; selecting another value cannot widen access.
HTTP 401	No valid accepted credential.	Check tanomis auth status, then log in again.
HTTP 403	The credential is valid, but this principal is not permitted for the selected projection or operation.	Have an owner verify membership, grant, and capability.
--tenant conflicts with the selected workspace	The explicit tenant and saved tenant differ.	Omit --tenant, select the intended workspace, or clear the selection.

Application requests consume bearer tokens and workspace headers as described in Platform API request basics, but that reference does not turn this human login into a backend credential.

Where to go next

• Quickstart: deploy and run your first agent.
• Workspaces: switching in the Console and the API.
• Journey commands: exact CLI syntax.