CLI Reference¶
The Skaha CLI provides a comprehensive command-line interface for interacting with the Science Platform. This reference covers all available commands and their options.
Getting Started
The CLI can be accessed using the skaha command in your uv environment:
Main Command¶
Description: Command Line Interface for Science Platform.
Global Options¶
| Option | Description |
|---|---|
--install-completion |
Install completion for the current shell |
--show-completion |
Show completion for the current shell, to copy it or customize the installation |
--help |
Show help message and exit |
Shell Completion
Enable shell completion for a better CLI experience by running:
🔐 Authentication Commands¶
skaha auth¶
Authenticate with Science Platform.
skaha auth login¶
Login to Science Platform with automatic server discovery.
Description: This command guides you through the authentication process, automatically discovering the upstream server and choosing the appropriate authentication method based on the server's configuration.
Options¶
| Option | Type | Default | Description |
|---|---|---|---|
--force |
Flag | - | Force re-authentication |
--debug |
Flag | - | Enable debug logging |
--dead |
Flag | - | Include dead servers in discovery |
--dev |
Flag | - | Include dev servers in discovery |
--details |
Flag | - | Include server details in discovery |
--discovery-url, -d |
TEXT | https://ska-iam.stfc.ac.uk/.well-known/openid-configuration |
OIDC Discovery URL |
skaha auth list / skaha auth ls¶
Show all available authentication contexts.
skaha auth switch / skaha auth use¶
Switch the active authentication context.
Arguments:
- CONTEXT (required): The name of the context to activate
skaha auth remove / skaha auth rm¶
Remove a specific authentication context.
Arguments:
- CONTEXT (required): The name of the context to remove
Permanent Action
This action permanently removes the authentication context and cannot be undone.
skaha auth purge¶
Remove all authentication contexts.
Options¶
| Option | Description |
|---|---|
--yes, -y |
Skip confirmation prompt |
Destructive Action
This command removes ALL authentication contexts. Use with caution!
🚀 Session Management Commands¶
skaha create¶
Create a new session on the Science Platform.
Arguments:
- KIND (required): Session type - one of: desktop, notebook, carta, headless, firefly
- IMAGE (required): Container image to use
- CMD [ARGS]... (optional): Runtime command and arguments
Options¶
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
--name |
-n |
TEXT | Auto-generated | Name of the session |
--cpu |
-c |
INTEGER | 1 | Number of CPU cores |
--memory |
-m |
INTEGER | 2 | Amount of RAM in GB |
--gpu |
-g |
INTEGER | None | Number of GPUs |
--env |
-e |
TEXT | None | Environment variables (e.g., --env KEY=VALUE) |
--replicas |
-r |
INTEGER | 1 | Number of replicas to create |
--debug |
- | Flag | - | Enable debug logging |
--dry-run |
- | Flag | - | Perform a dry run without creating the session |
Create a Headless Session with Custom Command
skaha ps¶
Show running sessions.
Options¶
| Option | Short | Type | Description |
|---|---|---|---|
--all |
-a |
Flag | Show all sessions (default shows just running) |
--quiet |
-q |
Flag | Only show session IDs |
--kind |
-k |
Choice | Filter by session kind: desktop, notebook, carta, headless, firefly |
--status |
-s |
Choice | Filter by status: Pending, Running, Terminating, Succeeded, Error |
--debug |
- | Flag | Enable debug logging |
skaha events¶
Show session events for debugging and monitoring.
Arguments:
- SESSION_IDS... (required): One or more session IDs
Options¶
| Option | Description |
|---|---|
--debug |
Enable debug logging |
skaha info¶
Show detailed information about sessions.
Arguments:
- SESSION_IDS... (required): One or more session IDs
Options¶
| Option | Description |
|---|---|
--debug |
Enable debug logging |
skaha open¶
Open sessions in a web browser.
Arguments:
- SESSION_IDS... (required): One or more session IDs
Options¶
| Option | Description |
|---|---|
--debug |
Enable debug logging |
Browser Integration
This command automatically opens the session URLs in your default web browser.
skaha logs¶
Show session logs for troubleshooting.
Arguments:
- SESSION_IDS... (required): One or more session IDs
Options¶
| Option | Description |
|---|---|
--debug |
Enable debug logging |
skaha delete¶
Delete one or more sessions.
Arguments:
- SESSION_IDS... (required): One or more session IDs to delete
Options¶
| Option | Short | Description |
|---|---|---|
--force |
-f |
Force deletion without confirmation |
--debug |
- | Enable debug logging |
Permanent Action
Deleted sessions cannot be recovered. Use --force to skip confirmation prompts.
skaha prune¶
Prune sessions by criteria for bulk cleanup.
Arguments:
- NAME (required): Prefix to match session names
- KIND (optional): Session kind - default: headless
- STATUS (optional): Session status - default: Succeeded
Options¶
| Option | Short | Description |
|---|---|---|
--debug |
- | Enable debug logging |
--help |
-h |
Show help message and exit |
Bulk Cleanup
Use prune to clean up multiple sessions that match specific criteria, especially useful for automated workflows.
📊 Cluster Information Commands¶
skaha stats¶
Show cluster statistics and resource usage.
Options¶
| Option | Description |
|---|---|
--debug |
Enable debug logging |
Resource Monitoring
This command provides insights into cluster resource usage, helping you understand available capacity.
⚙️ Client Configuration Commands¶
skaha config¶
Manage client configuration settings.
skaha config show / skaha config list / skaha config ls¶
Display the current configuration.
skaha config path¶
Display the path to the configuration file.
Configuration Location
Use this command to find where your configuration file is stored for manual editing if needed.
skaha version¶
View client version and system information.
Options¶
| Option | Default | Description |
|---|---|---|
--debug / --no-debug |
--no-debug |
Show detailed information for bug reports |