CLI Reference¶
Use canfar for Authentication, Science Platform Server selection, Session
management, Container Images, and client configuration.
canfar --help
Authentication and Servers¶
canfar login¶
canfar login [IDP] [OPTIONS]
| Option | Use |
|---|---|
--force, -f |
Force re-authentication. |
--debug |
Enable debug logging. |
--dev |
Include development Servers during discovery. |
--timeout, -t |
HTTP timeout in seconds during login. Default: 2. |
Examples:
canfar login
canfar login cadc
canfar login srcnet --force
canfar auth login is a deprecated compatibility alias.
canfar auth¶
canfar auth
canfar auth show
canfar auth ls
canfar auth use IDP
canfar auth rm IDP [--force]
canfar auth purge --force
| Command | Use |
|---|---|
auth / auth show |
Show active Authentication state. |
auth ls |
List saved Authentication records. |
auth use IDP |
Switch active Authentication by canonical IDP key. |
auth rm IDP |
Remove one Authentication record and its Servers. |
auth purge --force |
Reset Authentication and Server state. |
Machine output is supported for auth / auth show and auth ls:
canfar auth show --json
canfar auth ls --yaml
canfar server¶
canfar server ls
canfar server use SELECTOR
| Command | Use |
|---|---|
server ls |
List Servers for the active IDP, discovering them when needed. |
server use SELECTOR |
Select a Server by name or URI. |
Use URIs in scripts because names can be ambiguous:
canfar server use ivo://cadc.nrc.ca/skaha
Sessions¶
canfar create¶
canfar create [OPTIONS] KIND IMAGE [-- CMD [ARGS]...]
| Option | Short | Use |
|---|---|---|
--name |
-n |
Session name. Defaults to a generated name. |
--cpu |
-c |
Fixed CPU cores. Omit for flexible allocation. |
--memory |
-m |
Fixed RAM in GB. Omit for flexible allocation. |
--gpu |
-g |
GPU count. |
--env |
-e |
Environment variable as KEY=VALUE. |
--replicas |
-r |
Number of replicas. Default: 1. |
--debug |
Enable debug logging. | |
--dry-run |
Parse parameters and exit. |
Examples:
canfar create notebook skaha/astroml:latest
canfar create --cpu 4 --memory 16 notebook skaha/astroml:latest
canfar create headless skaha/terminal:1.1.2 -- python /arc/projects/demo/run.py
canfar ps¶
canfar ps [OPTIONS]
| Option | Short | Use |
|---|---|---|
--all |
-a |
Show all Sessions. Default shows running Sessions. |
--quiet |
-q |
Print only Session IDs. |
--kind |
-k |
Filter by Session Kind. |
--status |
-s |
Filter by status. |
--debug |
Enable debug logging. |
Machine output:
canfar ps --json
canfar ps --yaml
--quiet is a human-output shortcut and is incompatible with machine output.
Inspect and clean up¶
canfar events SESSION_ID...
canfar info SESSION_ID...
canfar logs SESSION_ID...
canfar open SESSION_ID...
canfar delete SESSION_ID... [--force]
canfar prune PREFIX [KIND] [STATUS]
Common flow:
canfar ps
canfar info $(canfar ps -q)
canfar open $(canfar ps -q)
canfar delete $(canfar ps -q)
Images and platform state¶
canfar image ls
canfar stats
Use canfar image --help and canfar stats --help for command-specific
options.
Client configuration¶
canfar config show
canfar config path
canfar config get console.width
canfar config get servers.canfar.url
canfar config set console.width 132
canfar version
canfar version --debug
config set parses values as YAML.
Machine output contract¶
| Rule | Behavior |
|---|---|
| Flags | --json or --yaml. |
| Placement | Put the flag after the command, for example canfar ps --json. |
| Conflict | --json --yaml exits 2. |
| stdout | Data payload only. |
| stderr | Diagnostics and errors. |
| Unsupported command | Exits 1 with a clear unsupported-machine-output message. |
| Ordering | List ordering is not guaranteed. |