auth¶

NAME¶

phyware auth — authenticate and manage sessions.

SYNOPSIS¶

phyware auth login           [OPTIONS]
phyware auth logout          [OPTIONS]
phyware auth status          [OPTIONS]
phyware auth token           [OPTIONS]
phyware auth refresh         [OPTIONS]
phyware auth switch          [OPTIONS] --host <URL>
phyware auth sessions list   [OPTIONS]
phyware auth sessions revoke [OPTIONS] <SESSION_ID>

DESCRIPTION¶

Starts the device-code OAuth flow. Pass --with-token to read a PAT from stdin. Pass --password to use email/password authentication.

logout¶

Revokes the current access token and removes credentials from the store.

status¶

Prints the active identity, scopes, token expiry, and host.

token¶

Prints the raw access token to stdout. Useful for piping to curl.

refresh¶

Validates the current token; refreshes it if it is close to expiry.

switch¶

Changes the active host (useful in multi-host setups).

sessions list¶

Lists all active sessions for a user.

sessions revoke¶

Revokes a specific session by ID.

OPTIONS¶

Flag	Type	Required	Default	Env
`--url`	string	No	`http://localhost:8000`	`PHYCLOUD_URL`
`--api-key`	string	No	—	`PHYCLOUD_API_KEY`
`--output`	enum	No	`table`	—

ARGUMENTS¶

Name	Required	Description
`SESSION_ID`	Yes (sessions revoke)	Session identifier

INPUT¶

For login --with-token: PAT read from stdin.

OUTPUT¶

Field	Type	Description
`user`	string	Authenticated user email
`scopes`	array	Granted OAuth scopes
`expiry`	string	Token expiry timestamp
`host`	string	Active API host

EXIT CODES¶

Code	Meaning
`0`	Success
`1`	Generic / connection error
`2`	Authentication / authorisation error
`3`	Resource not found
`4`	Validation error
`5`	Server-side error

EXAMPLES¶

# Device-code login
phyware auth login --host https://cloud.phyware.io

# PAT login via stdin
echo "$PAT" | phyware auth login --with-token

# Check authentication status
phyware auth status

# Print access token (e.g. for curl)
phyware auth token

# Refresh the current token
phyware auth refresh

# Switch active host
phyware auth switch --host https://staging.phyware.io

# List sessions
phyware auth sessions list --user-id usr_abc123

# Revoke a session
phyware auth sessions revoke ses_abc123

AGENT NOTES¶

Always call auth status before other commands to confirm valid credentials. Use auth token to inject tokens into external HTTP calls. For CI/CD set PHYCLOUD_API_KEY instead of calling auth login. Requires no scope (login/status/token/refresh); admin:sessions for sessions operations.

ERRORS¶

Code	Message	Remediation
`UNAUTHORIZED`	Invalid credentials	Re-run `auth login`
`EXPIRED`	Token expired	Run `auth refresh` or re-login
`NOT_FOUND`	Session not found	Check `SESSION_ID`