CLI reference

The canfar command manages Authentication, Science Platform Server selection, Sessions, Container Images, data sources, and client configuration. Run canfar --help or append --help to any command for the installed options.

Development builds also discover installed CLI extensions. They appear under Extensions in root help and define their own options.

Canonical commands

The root keeps Session and information operations as leaves. Authentication, Server, data, image, and configuration operations remain grouped:

Area	Commands
Authentication and Server Selection	login, auth, server
Sessions	create, ps, events, info, open, logs, renew, delete, prune
Platform information	stats, image ls
Client configuration	config show, config get, config set, config path, version
Data	data and its embedded file commands

There are no extra command names between the root and these leaves. In particular, Session creation is canfar create, and login is canfar login.

Root logging options

Root logging options must come before the command:

canfar --log-level debug ps
canfar -v ps
canfar --log-file ./logs/canfar.jsonl ps

Option	Effect
--log-level LEVEL	critical, error, warning, info, or debug.
-v	info progress; -vv or more selects debug.
--log-file PATH	Add the rotating JSON Lines file sink.

See Logging for precedence, stream routing, file records, and setup errors.

Authentication and Servers

Login

Command syntax

canfar login [IDP] [OPTIONS]

IDP is an optional canonical Identity Provider key. Without it, the CLI prompts for one. The options are:

Option	Effect
--force, -f	Re-authenticate an existing Authentication Record.
--dev	Include development registries and endpoints during discovery.
--timeout, -t	HTTP timeout in seconds; default 10.

canfar login cadc
canfar login srcnet --force

During discovery, login shows a live grid of the Servers it found, counting those discovered, timed out, unreachable, or failed, and suggests a longer --timeout when a Server times out; --log-level info labels each square with its Server Name. The interactive credential flow, discovery outcomes, and Server Selection are described in Authentication and Servers.

Authentication

Command syntax

canfar auth
canfar auth show
canfar auth ls
canfar auth use IDP
canfar auth rm IDP [--force]
canfar auth purge --force

canfar auth is the same active-Authentication view as canfar auth show. auth use selects a saved Authentication Record; auth rm also removes the associated Servers; auth purge --force resets Authentication and Server state.

Server Selection

canfar server ls
canfar server use SELECTOR

SELECTOR may be a Server Name or an IVOA URI. server ls lists Servers for the active IDP and discovers them when no saved Servers are available. It shows each Server's flexible and fixed CPU and memory limits, GPUs, and interactive Session limit, or unknown when the Server does not advertise one; machine output has them under resources.

Sessions

Create

Command syntax

canfar create [OPTIONS] KIND IMAGE [-- CMD [ARGS]...]

KIND is one of desktop, notebook, carta, headless, firefly, or contributed. IMAGE is a CANFAR Container Image such as skaha/astroml:latest; the client adds the CANFAR registry and :latest when they are omitted. That shorthand always expands to images.canfar.net, so on a Server that trusts another registry, write the full REGISTRY/PROJECT/IMAGE:TAG name from canfar image ls. Accepted ranges for every option are in Session limits.

Option	Effect
--name, -n	Session name; a generated name is used by default.
--cpu, -c	Requested CPU cores.
--memory, -m	Requested RAM in GB.
--gpu, -g	Requested GPU count.
--env, -e KEY=VALUE	Set an environment variable; repeat as needed.
--replicas, -r	Number of Sessions, 1 to 256; default 1.
--debug	Print the parsed Session request.
--dry-run	Validate and print the request without creating a Session.
--output, -o	Emit created Session IDs as json or yaml.

Everything after -- belongs to the container command. The first token is the command and the remaining tokens are its arguments, even when they look like CANFAR options:

canfar create headless skaha/terminal:1.1.2 -- python /arc/projects/demo/run.py
canfar create headless skaha/terminal:1.1.2 -- worker --output json -o yaml

The --output option must appear before --. --dry-run cannot be combined with machine output. --cpu, --memory, --gpu, and --replicas accept the ranges canfar create --help shows. When the active Server's limits are known, the --cpu, --memory, and --gpu ranges narrow to the values both the client and that Server accept, and the default shows how far a flexible Session can burst, for example [default: flexible ≤ 16]. A Server without GPUs accepts only --gpu 0, which requests none. A value outside a range is a usage error: exit code 2 with Invalid value on stderr, before any request is sent, --dry-run included.

List Sessions

Command syntax

canfar ps [OPTIONS]

Option	Effect
--all, -a	Include all statuses; otherwise show Pending and Running.
--quiet, -q	Print matching Session IDs in human mode.
--kind, -k	Filter by Session Kind.
--status, -s	Pass a status filter to the Science Platform.
--debug	Print Session response warnings.
--output, -o	Emit the filtered Session response array as json or yaml.

ps stays a thin operation over Session.fetch(): --kind and --status are sent to the fetch call, then the CLI applies the running/default or --all view to the returned responses. --quiet follows that same filter, including when combined with --all, and is not available with --output.

canfar ps
canfar ps --all --kind headless
canfar ps -o json

Inspect, open, and remove

These leaves accept one or more Session IDs and produce human-readable output:

Command	Purpose
canfar events SESSION_ID...	List Science Platform events.
canfar info SESSION_ID...	Show Session details; --debug adds response warnings.
canfar logs SESSION_ID...	Show Session logs.
canfar open SESSION_ID...	Open ready Sessions in new browser tabs.
canfar renew SESSION_ID...	Reset the lifetime of interactive Sessions.
canfar delete SESSION_ID... [--force]	Delete Sessions, confirming unless --force is used.
canfar prune PREFIX [KIND] [STATUS]	Delete matching names; defaults to headless and Succeeded.

prune treats a plain PREFIX as a literal prefix. A value containing regex metacharacters is treated as a regular expression. Quote such values so the shell does not expand them:

canfar prune 'notebook.*' notebook Completed

Platform information

canfar stats
canfar image ls
canfar image ls --kind notebook
canfar version
canfar version --debug

stats prints CPU and RAM usage, plus GPU usage when the server includes it. Maximum Resource Requests shows the Fixed and Flexible CPU and RAM maxima saved for your selected server, as listed by canfar server ls. Missing limits are shown as unknown; these request limits do not guarantee that capacity is currently available.

image ls lists Container Images and accepts the image-kind filter shown above. version --debug prints client, Python, operating-system, and dependency details for a bug report; it is not a logging control.

Help and feedback

canfar feedback

Clients from v1.5.0 onward print the GitHub chooser URL without authentication, configuration reads, browser opening, or diagnostics collection. Use it for problems, questions, ideas, and documentation feedback. See the community guidelines for follow-up and private support.

Data and configuration

canfar data --help
canfar config show
canfar config get console.width
canfar config set console.width 132
canfar config path

Data operands use an explicit Storage Identifier, for example arc:/home/user/file.fits or local:/tmp/file.fits. See Data commands for the embedded commands. Configuration keys use dotted paths; values passed to config set are parsed as YAML. See Authentication and Servers for the persisted Authentication, Server, and active-selection shape.

The Data tools have been in beta since v1.5.0. Bare Data and subcommand help show a beta notice; operations and Python calls do not.

Machine output

The leaf option -o/--output accepts only json or yaml. It is available on the data-producing forms auth (the default active view), auth show, auth ls, server ls, create, ps, config show, and config get:

canfar auth show -o json
canfar server ls --output yaml
canfar create headless skaha/terminal:1.1.2 -o json
canfar config get active.server -o json

The payload is the same Python result used by that command after its normal filtering. For example, create -o json is a raw list of Session IDs and ps -o json is a filtered array of Session response objects; neither is wrapped in a command-specific envelope. Human active-Server banners and logs never precede the machine payload on stdout. Diagnostics and errors use stderr.

Failures and exit status

A command that fails exits with a nonzero status. In human mode the message and a hint go to stderr. In machine mode stderr carries one structured object with a stable code, a message, and a hint, and stdout stays empty:

{"code": "authentication.required", "message": "Not authenticated with 'cadc'.\nReason: X.509 certificate has not been issued.", "hint": "Run `canfar login cadc` and retry."}

Code	Meaning	Next step
authentication.required	Credentials are missing, or OIDC refresh requires a new login.	Run canfar login IDP with the IDP named in the hint.
authentication.expired	The saved credential has expired.	Run canfar login IDP with the IDP named in the hint.
authentication.credential_invalid	A credential is saved but cannot be used, such as an unreadable certificate.	Check canfar auth show, then log in again.
transport.failure	A request to the Science Platform or IDP failed.	Follow the hint, check connectivity, then retry.

Codes are stable; message and hint wording can change. Every command that contacts a Server reports a missing login this way, including the human-text commands info, events, logs, open, stats, and image ls.

Put -o/--output after the command that owns it. Root -o, --json, and --yaml are not options, and commands without machine output reject -o. For create, -o is parsed only before --; after the delimiter it is a container-command token.