TrueNAS SCALETrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.


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.

Mail Namespace

The mail namespace has three commands and is based on configuration management functions found in the SCALE API and web UI. It provides access to email configuration methods through the system namespace commands.

Mail Commands

The following mail commands allow you to view or edit mail settings and to send an email using configured settings. You can enter commands from the main CLI prompt or from the system namespace prompt.

Config Command

The config command displays the current system email configuration.

Using the Config Command


config does not require entering properties or arguments. Enter the command and then press Enter. The command returns a table containing current email configuration settings.


From the CLI prompt, enter:

system mail config

Press Enter.

Command Example
system mail config
|             id | 1                   |
|      fromemail |       |
| outgoingserver | |
|           port | 587                 |
|       security | TLS                 |
|           smtp | true                |
|           user |       |
|           pass | passw0rt            |
|       fromname | TrueNAS             |
|          oauth | <dict>              |

Send Command

The send command sends an email from the system. A valid email send method must be configured before sending an email.

Using the Send Command


The send command has one required property, mail_message, which has two required sub-properties, subject and text, and nine optional sub-properties (see chart below), and one optional property, mail_update, which uses the same properties as the update command.

Enter mail_message or mail_update properties as an array enclosed in curly brackets {}. Enclose properties and values in double quotes, do not double quote boolean values, separate properties from values using a colon, and separate property/value pairs using a comma.

mail_message Properties
PropertyRequiredDescriptionSyntax Example
subjectYesEnter a subject for the email.“subject”:"test"
textYes*Required if html is not set. Enter the email body text. Text is formatted to HTML using Markdown and rendered using the default email template.“text”:"Test message"
htmlYes*Required if text is not set. Enter the email body text and HTML formatting.“html”:"Some HTML"
toNoEnter the address to receive the email. If not set, defaults to the configured admin email address.“to”:""
ccNoEnter an address to carbon copy (CC) on the email.“cc”:""
intervalNoUse to define a minimum interval in seconds for the email job to forbid duplicate emails within a given time frame. Defaults to null.“interval”:"60"
channelNoEnter the name of the channel to receive the email, if needed.“channel”:"notifications"
timeoutNoEnter the send operation timeout limit in seconds. If not set, timeout defaults to 300, or five minutes.“timeout”:"300"
attachmentsNoFull documentation for this property is being developed.
queueNoSet true to allow email queuing or false to disallow. Defaults to true.“queue”:false
extra_headersNoUse to specify any additional email headers, such as to designate the email priority.“extra_headers”:{"priority":"urgent"}


From the CLI prompt, enter:

system mail send mail_message={“subject”:"test",“text”:"Test message"}

Where test is the email subject and Test message is the email body text. Press Enter.

Command Example
system mail send mail_message={"subject":"test","text":"Test message."}
[0%] ...
[100%] ...

Update Command

The update command configures the system email send method using either SMTP or OAuth.

Using the Update Command


update has 9 optional properties (see the tables in Update Properties below). Enter the command followed by one or more property/value pairs. Enclose any values using special characters, for example a period . or @ in double quotes. Separate multiple property/value pairs with a space.

To configure the system email using SMTP, enter the mail update command followed by the SMTP properties.

To configure using OAuth, first obtain a valid OAuth token from your email provider. For example, see Authenticating with Google services. Enter the mail update command with the property OAuth followed by an array containing the client_id, client_secret, and refresh_token properties and values from the token.

The TrueNAS SCALE web UI provides a streamlined experience for Gmail OAuth authentication. See Setting Up System Email for details.

Press Enter. The command returns an empty line.

Use config to view updated configuration and send to confirm configuration by sending a test email.

Update Properties

SMTP Properties
PropertyRequiredDescriptionSyntax Example
fromemailYesThe email address to use for sending emails. You must first configure the user account email in Credentials > Local Users.fromemail=""
fromnameNoThe name to show in front of the sending email address, for example: TrueNAS.fromname=TrueNAS
outgoingserverYesHost name or IP address of SMTP server to use for sending emails.outgoingserver=""
portYesSMTP port number. Typically 25, 465 (secure SMTP), or 587 (submission).port=587
securityNoEnter the security type to use. Options are PLAIN (no encryption), SSL (Implicit TLS), or TLS (STARTTLS). See email encryption for more information on
smtpNoSet to true to enable SMTP AUTH using PLAIN SASL. Requires a valid user name and password.smtp=true
userYes*Required when smtp is true. The user name for the sending email account, typically the full email address.user=""
passYes*Required when smtp is true. The password for the sending email account.pass=passw0rt

OAuth Properties
PropertyRequiredDescriptionSyntax Example
client_idYesEnter the OAuth client id.“client_id”:"12345678910…"
client_secretYesEnter the OAuth client secret.“client_secret”:"GOCSPX…eQ2_"
refresh_tokenYesEnter the OAuth refresh token.“refresh_token”:"1//04KmHpZzM…YUwfI"


From the CLI prompt, enter:

system mail update property=value

Where property is one of the optional properties (see table) and value is the setting you want to apply. Press Enter.

Command Example -- SMTP system mail update fromemail="" fromname=TrueNAS outgoingserver="" port=587 security=TLS smtp=true user="" pass=passw0rt

Command Example -- OAuth system mail update oauth={“client_id”:"12345678910…",“client_secret”:"GOCSPX…eQ2_",​“refresh_token”:"1//04KmHpZzM…YUwfI"}