Sam Reference

Sam is a Command Line Interface (CLI) tool created in order to easily setup and maintain Raspberry Pi and similar devices right from your computer, without having to create an SSH session and typing complex, low-level commands.

Sam is intented to be installed on your desktop computer or your laptop.


Here is the result of running sam help:

sam connect <HOSTNAME_OR_IP> Connect to a device
sam devices Discover devices on your local network
sam disconnect Disconnect from a device
sam hass Home assistant commands
sam init Install Snips Platform components
sam install Install assistant or skills
sam login Login to the console
sam logout Logout of the console
sam mqtt Control MQTT service
sam reboot Reboot the device
sam service Display logs or restart Snips services
sam set-hostname <HOSTNAME> Set device hostname
sam setup Setup hardware
sam sound-feedback <toggle> Toogle sound feedback on or off
sam status Show the status of your device
sam test Test microphone or speaker
sam update-assistant Update the assistant already installed on the device
sam update Update Snips platform on your device
sam watch Show MQTT logs
--version Show version number [boolean]
--help Show help [boolean]

Core Features

Basic device control

Listing Raspberry Pi devices on the network

sam devices

List devices on the network whose Mac address matches that of a Raspberry Pi.

Connecting to a remote device

sam connect <HOSTNAME_OR_IP>

Establish an SSH connection to a device, saving the public key to the device in order to maintain the connection across sessions without requiring a password.

Disconnecting from a remote device

sam disconnect

Disconnect Sam from the device, clearing the cached session info on the local machine.

Rebooting a device

sam reboot

Reboot the device that Sam is currently connected to. You will be shown a loading message until connection to the device is re-established.

Setting the device hostname

sam set-hostname

Change device hostname. Then reboot it (sam reboot) and wait until it comes back online.

Managing the Snips Platform and Console

Installing the Snips Platform

sam init

Installs the Snips core components, including Snips Manager to execute apps.

Updating the Snips Platform

sam update

Update the Snips Platform and its dependencies.

Checking MQTT messages

sam watch

Watch for MQTT messages passed on the broker to which the device is connected.

Enable or disable audio feedback

sam sound-feedback <on|off>

Toggle sound feedback on or off.

Connecting to the Snips Console

Logging in to the Console

sam login

Log in to the Snips Console. This will ask you for your credentials as provided on, allowing you to install and update assistants directly from the command line.

Logging out of the Console

sam logout

Log out of the Snips Console.

Managing Snips assistants

Installing an assistant from the Snips Console

sam install assistant

Install an assistant from the Console and the associated apps. Make sure you are logged in to the Console using sam login.

Updating an assistant from the Snips Console

sam update-assistant

Fetch a newer version of the assistant present on the device.

Installing actions from the Snips Console

sam install actions

Installs only the actions contained in the assistant.

Managing Snips Platform services

Displaying service logs

sam service log [<SERVICE_NAME [, SERVICE_NAME...]>]

Show the logs of one or more services. If no service name is provided, all logs are shown.

Starting a service

sam start [<SERVICE_NAME [, SERVICE_NAME...]>]

Start one or more services. If no service name is provided, all services are started.

Restarting a service

sam restart [<SERVICE_NAME [, SERVICE_NAME...]>]

Restart one or more services. If no service name is provided, all services are restarted.

Stopping a service

sam stop [<SERVICE_NAME [, SERVICE_NAME...]>]

Stop one or more services. If no service name is provided, all services are stopped.

Checking the status of the device

sam status

Fetch the device status, including the OS version, info about the installed assistant (name, wake word, language), and the status of all Snips services.

Hardware configuration

Setting up the audio

sam setup audio

Start a wizard to set up the audio input and output sources used by the Snips Platform.

Note that this setup also allows you to set up audio on your Snips Maker Kits. It will install the ReSpeaker 2-mic hat audio drivers as well as an action to control the leds.

Enabling audio echo cancellation through PulseAudio (Beta)

sam setup aec

Audio echo cancellation (AEC) is meant to be used with the Maker Kit, which will improve wake word detection and automatic speech recognition performance when music is played on the device. It is a feature of PulseAudio. In order to activate it, Sam will therefore also install PulseAudio. This action can't be undone from Sam. However you can disable AEC and PulseAudio manually on your Pi.

Testing the device microphone

sam test microphone

Starts recording audio on the device, and play it back after pressing Enter. Then plays back the sound, allowing you to test the quality of the audio capture.

Testing the device speaker

sam test speaker

Play a sound on the speaker.

Extra Features

Home Assistant

Installing Home Assistant

sam hass install

Install Home Assistant on your device in a Python virtual environment, following the Home Assistant Documentation.

Restarting Home Assistant

sam hass restart

Restart Home Assistant on the device.

Displaying the Home Assistant configuration

sam hass configuration

Display the current configuration.yaml of Home Assistant.

Issues or Comments

Please report issues or give feedback on the Snips Issue Tracker.