CLI Reference¶
The Canfar 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 canfar command in your uv environment:
uv run canfar --help
Main Command¶
canfar [OPTIONS] COMMAND [ARGS]...
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:
canfar --install-completion
🔐 Authentication Commands¶
canfar auth¶
Authenticate with Science Platform.
canfar auth login¶
Login to Science Platform with automatic server discovery.
canfar auth login [OPTIONS]
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 |
Basic Login
canfar auth login
Login with Debug Information
canfar auth login --debug --details
canfar auth list / canfar auth ls¶
Show all available authentication contexts.
canfar auth list [OPTIONS]
Example
canfar auth list
canfar auth switch / canfar auth use¶
Switch the active authentication context.
canfar auth switch CONTEXT
Arguments:
- CONTEXT (required): The name of the context to activate
Example
canfar auth switch production
canfar auth remove / canfar auth rm¶
Remove a specific authentication context.
canfar auth remove CONTEXT
Arguments:
- CONTEXT (required): The name of the context to remove
Permanent Action
This action permanently removes the authentication context and cannot be undone.
canfar auth purge¶
Remove all authentication contexts.
canfar auth purge [OPTIONS]
Options¶
| Option | Description |
|---|---|
--yes, -y |
Skip confirmation prompt |
Destructive Action
This command removes ALL authentication contexts. Use with caution!
🚀 Session Management Commands¶
canfar create¶
Create a new session on the Science Platform.
canfar create [OPTIONS] KIND IMAGE [-- CMD [ARGS]...]
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 Jupyter Notebook
canfar create --cpu 4 -m 8notebook skaha/scipy-notebook:latest
Create a Headless Session with Custom Command
uv run canfar create headless skaha/terminal:1.1.2 -- env
canfar ps¶
Show running sessions.
canfar ps [OPTIONS]
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 |
List All Sessions
canfar ps --all
List Only Notebook Sessions
canfar ps --kind notebook
canfar events¶
Show session events for debugging and monitoring.
canfar events [OPTIONS] SESSION_IDS...
Arguments:
- SESSION_IDS... (required): One or more session IDs
Options¶
| Option | Description |
|---|---|
--debug |
Enable debug logging |
Example
canfar events abc123 def456
canfar info¶
Show detailed information about sessions.
canfar info [OPTIONS] SESSION_IDS...
Arguments:
- SESSION_IDS... (required): One or more session IDs
Options¶
| Option | Description |
|---|---|
--debug |
Enable debug logging |
Example
canfar info abc123
canfar open¶
Open sessions in a web browser.
canfar open [OPTIONS] SESSION_IDS...
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.
Example
canfar open abc123 def456
canfar logs¶
Show session logs for troubleshooting.
canfar logs [OPTIONS] SESSION_IDS...
Arguments:
- SESSION_IDS... (required): One or more session IDs
Options¶
| Option | Description |
|---|---|
--debug |
Enable debug logging |
Example
canfar logs abc123
canfar delete¶
Delete one or more sessions.
canfar delete [OPTIONS] SESSION_IDS...
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.
Delete with Confirmation
canfar delete abc123
Force Delete Multiple Sessions
canfar delete abc123 def456 --force
canfar prune¶
Prune sessions by criteria for bulk cleanup.
canfar prune [OPTIONS] NAME [KIND] [STATUS]
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 |
Prune Completed Headless Sessions
canfar prune "test-" headless Running
Bulk Cleanup
Use prune to clean up multiple sessions that match specific criteria, especially useful for automated workflows.
📊 Cluster Information Commands¶
canfar stats¶
Show cluster statistics and resource usage.
canfar stats [OPTIONS]
Options¶
| Option | Description |
|---|---|
--debug |
Enable debug logging |
Example
canfar stats
Resource Monitoring
This command provides insights into cluster resource usage, helping you understand available capacity.
⚙️ Client Configuration Commands¶
canfar config¶
Manage client configuration settings.
canfar config show / canfar config list / canfar config ls¶
Display the current configuration.
canfar config show [OPTIONS]
Example
canfar config ls
canfar config path¶
Display the path to the configuration file.
canfar config path [OPTIONS]
Example
canfar config path
Configuration Location
Use this command to find where your configuration file is stored for manual editing if needed.
canfar version¶
View client version and system information.
canfar version [OPTIONS]
Options¶
| Option | Default | Description |
|---|---|---|
--debug / --no-debug |
--no-debug |
Show detailed information for bug reports |
Basic Version Info
canfar version
Detailed Debug Information
canfar version --debug