Get a Quote     (408) 943-4100   TrueNAS Discord VendOp_Icon_15x15px Commercial Support
TrueNAS.com Software Systems Company Community Security iX Portal Download
TrueNAS CORE TrueNAS Enterprise TrueNAS SCALE TrueCommand Compare Editions Software Status FreeNAS
Compare Systems M-Series X-Series R-Series Mini Series
Contact Us iXsystems Careers Clients Reviews
TrueNAS GitHub Community Forum Discord TrueNAS Merch Store
Application Backup and Archival Cloud Media Workflows Video Surveillance Virtualization
Industry Education Government Healthcare Research / AI / ML Media & Entertainment
Enterprise Support Community Support Documentation TrueNAS Security FAQ iX Blog TrueNAS Blog
Case Studies White Papers Solution Briefs iX Portal Plugins & Apps ZFS Videos
Download TrueNAS CORE Download TrueNAS SCALE Get TrueNAS Enterprise Where to Buy
  1. TrueNAS SCALE 22.12 (Archived)
  2. /
  3. CLI Reference Guide
Edit page
TrueNAS SCALETrueNAS SCALE Documentation Archive
This content follows the TrueNAS SCALE 22.12 (Bluefin) releases. Archival documentation is provided for reference only and not actively maintained.
Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.

CLI Reference Guide

  9 minute read.

Last Modified 2024-03-19 08:47 EDT

The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!

Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!

The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.

The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.

Launching the TrueNAS CLI

You can access the TrueNAS CLI through either the Console Setup Menu or from the Shell screen in the SCALE web UI.

Entering the TrueNAS CLI from Console Setup Menu

To open the TrueNAS CLI from the Console Setup Menu, enter 6.

CSMCLIlaunch

To access the TrueNAS CLI when the Linux shell is active, enter cli.

Entering the TrueNAS CLI in the Linux Shell

To access the TrueNAS CLI from the SCALE web UI, go to System Settings > Shell, then enter cli at the system prompt and press Enter.

EnterCLIinShell

Exiting the TrueNAS CLI from the Linux Shell

To exit the TrueNAS CLI, enter quit or exit.

Getting Help

The SCALE CLI includes help text for some namespaces and commands through the both the man, and ls commands. To see the basic commands from any namespace, enter help.

Use the man command to show the help text for a namespace or command with options. Type man namespacename or man commandname to display the help text for that namespace or command.

Use the ls command while in a child namespace to view a list of commands and the help text descriptions. You can use the ls command for some commands that show an autofill list of options to display a list of those options with help text descriptions.

CLIListForCommandWithOptions

Note, not all namespaces, commands, or commands with options include help text.

Using ls with some commands with autofill options does not always display a list view or help text for the options.

Accessing Basic Commands

The TrueNAS CLI includes basic commands available from the CLI prompt or while in any namespace in the CLI. To access these basic options, enter ? or help, then press Enter. The list of basic commands displays.

CLIBasicCommands

CommandDescription
..Moves up one level. For example, from a namespace like auth, enter .. to return to the CLI prompt. From a child namespace like interfaces, use .. to return to the network parent namespace.
exitLeave the TrueNAS CLI and return to the system prompt.
lsLists the namespaces and commands from the active CLI level. For example, at the top level, ls displays the main namespaces in the TrueNAS CLI, or at a main namespace level, displays the additional namespaces or commands for that level.
manWhen in a namespace, displays the help text for the command that follows man. For example, while in the network namespace, enter man create to see the help text for the create command.
menuDisplays the Console setup menu in the TrueNAS CLI. Type 6 to exit the menu and return to the CLI prompt.
?Displays the list of basic commands for the TrueNAS CLI.
/Returns to the main TrueNAS CLI prompt from any namespace.
.modeGets or sets the output mode.
.stacksEnables/disables printing stack traces for errors.

The TrueNAS CLI provides eleven top level (parent) namespaces that correspond to SCALE UI functions but not all namespaces mirror the UI counterpart. For example, the system name space includes alerts and certificates in the CLI but in the UI the counterpart is System Settings, and neither Alerts or Certificates are found under System Settings. Each parent namespace has child namespaces and commands.

Use the ls command to view the list of namespaces or commands.

CLIBasicCommands

Parent and Child Namespaces

NamespaceDescription
accountProvides access to user and group child namespaces and commands. In the UI these are found on the **Credentials screen.
appProvides access to application child namespaces and commands including catalog, chart_release, container, docker, and kubernetes.
authProvides access to authentication child namespaces and commands including api_key, privilege, sessions, and two_factor.
directory_serviceProvides access to directory services child namespaces and commands including activedirectory, idmap, kerberos, and ldap.
filesystemProvides access to the acltemplate child namespace.
networkProvides access to network child namespaces and commands including configuration, dns, interface, ipmi, route, and static_route.
serviceProvides access to service child namespaces and commands including cluster, ctdb, dyndns, ftp, gluster, ipmi, nfs, openvpn, rsync, rsync_mod, s3, smart, smb, snmp, ssh, tftp, vm, and webdav.
sharingProvides access to sharing child namespaces and commands including iscsi, nfs, smb, and webdav.
storageProvides access to storage child namespaces and commands including dataset, disk, enclosure, filesystem, pool, resilver, scrub, snapshot, and vmware.
systemProvides access system child namespaces and commands including acme, advanced, alert, boot, bootenv, certificate, config, core, failover, general, keychain_credential, kmip, mail, ntp_server, reporting, support, system_dataset, truecommand, truenas, tunable, update, and version.
taskProvides access to task child namespaces and commands including cloud_sync, cron_job, replication, rsync, smart_test, and snapshot.

Entering Namespaces and Commands

CLI namespaces and commands are case sensitive. Enter commands in lower case unless the CLI autofill indicates otherwise.

To enter a namespace or command, begin typing the name. The CLI displays an autofill list that begins with the letter typed and is available in that part of the CLI. For example, the autofill list at the main CLI prompt includes only the parent namespaces that begin with the letter typed.

CLIAutofillList

To enter a basic command such as checking current configuration settings in a namespace, enter namespace childnamespace config. The system displays the configured settings for the namespaces preceding the config command.

You can enter a namespace, child namespace, command, command options and option=value pairs from the main CLI prompt using autofill options. For example, parent namespace child namespace command option=value.

EnterFullCommandAtCLIPrompt

You can enter a namespace, then enter the child namespace, command, then select the command option to enter the option=value pair from the namespace prompt.

EnterFullCommandAtNamespacePrompt

A command without options does not show an autofill list. Press space to see if the command has more options or wants input, or press Enter to apply the command.

To go up one namespace or command level, enter ... Enter / to return to the CLI prompt.

Using Keyboard Arrow Keys

Use the up or down arrow keys to select an autofill option, then press space to apply it.

You can use Backspace to erase entered text to start over.

Use the left arrow to move the cursor to the left in a command string where you change the text or use Delete to remove anything to the right of the cursor.

Use the right arrow to move the cursor to the right to the end of the command string to either continue entering command options, or to press Enter to apply the command.

Command Syntax

TrueNAS CLI command structure varies by namespace. CLI commands can include arguments, options, and or option=value pairs.

Command options that require a single value automatically add the = delimiter after the option on the autofill list and after reaching the end of the command option inputs. This is an option=value pair.

Some commands allow entering multiple option=value pairs. These option=value pairs are enclosed in curly brackets, but can also include square or angle brackets enclosed in the curly brackets.

Each namespace article includes command syntax examples for each namespace.

Using the Interactive Arguments Editor

Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).

Enter account user create -- to open the user_create TUI.

InteractiveArgumentsEditor

Both username: and full_name: are required and enabled by default.

Either group: or group_create: and password: or password_disabled: are also required properties. You must enable and configure one property for each pair.

All other disabled properties are optional.

To provide values for enabled properties, enter a value following the provided property. For example, username: testuser.

To enable a property, remove # from the corresponding line and then enter its value. For example,


    # Integer: If `uid` is not provided it is automatically filled with the next one available.
    # uid:

is entered as:


    # Integer: If `uid` is not provided it is automatically filled with the next one available.
    uid: 3000

Where 3000 is an available user identification (UID) number.

Enter values for all required and any optional properties you want to configure. Save the modified file then Quit to exit the TUI and execute the user_create command.

Namespace Documentation

There are eleven primary or parent namespaces. Each has additional child namespaces and commands to perform various actions.

  • ⎙ Download or Print: View the entire CLI Reference Guide as a single page for download or print.

  • Account: Introduces the TrueNAS CLI account namespace, used to access user and group child namespaces and commands.

  • App: Introduces the TrueNAS CLI app namespace, used to access child namespaces and commands including catalog, chart_release, container, docker, and kubernetes.

  • Auth: Introduces the TrueNAS CLI auth namespace, used for currently logged-in user authentication and generating an access token for the web UI.

  • Directory Service: Introduces the TrueNAS CLI directory_service namespace, used to access child namespaces and commands including activedirectory, idmap, kerberos, and ldap.

  • Filesystem: Introduces the TrueNAS CLI filesystem namespace, used to access the acltemplate child namespace.

  • Network: Introduces the TrueNAS CLI network namespace, used to configure network settings found in the API and web UI.

  • Service: Introduces the TrueNAS CLI service namespace, used to access child namespaces and commands including cluster, ctdb, dyndns, ftp, gluster, ipmi, nfs, openvpn, rsync, rsync_mod, s3, smart, smb, snmp, ssh, tftp, vm, and webdav.

  • Sharing: Introduces the TrueNAS CLI sharing namespace, used to access child namespaces and commands including iscsi, nfs, smb, and webdav.

  • Storage: Introduces the TrueNAS CLI storage namespace, used to access child namespaces and commands including dataset, disk, enclosure, filesystem, pool, resilver, scrub, snapshot, and vmware.

  • System: Introduces the TrueNAS CLI system namespace that configures system related settings found in the API and web UI.

  • Task: Introduces the TrueNAS CLI task namespace, used to access child namespaces and commands including cloud_sync, cron_job, replication, rsync, smart_test, and snapshot.