Before using the Sama CLI, you need to specify the Sama Project ID, API Key or Sama credentials, all which are provided by your Sama project manager. The following instructions also assume that your Sama Project manager has already configured all the neccessary Sama Project inputs and outputs.

Create a new folder and set the current working directory to it. For example,

$ mkdir my_sama_project
$ cd my_sama_project

Run the sama init command:

$ sama init
? Project ID: YOUR_SAMA_PROJECT_ID
? Email: (Any email to get notified when task creation is done)
? How would you like to authenticate the Sama CLI? (Choose one of the following)
       Option 1: Log in with Sama username and password - Your web browser will open and ask you to log in with your Sama credentials. Once logged in, copy and paste the Login token into the CLI.
       Option 2: Provide API Key - YOUR_SAMA_API_KEY

The above data will be saved into .sama.yaml (and .sama.creds.yaml if authenticating with Sama credentials) in your current working directory.

You'll then be prompted to create the mapping json which contains your Sama Project inputs and maps it to values generated by the CLI. The CLI will attempt to auto-generate the mapping json by looking at the required inputs set up in your Sama Project. See Configuring the mapping json below for more info.

? No mapping json found in project. Would you like to auto-generate it? Yes
{
  "name": "{{ .BaseName }}",
  "url": "{{ .URL }}",
  "client batch id": "{{ .ClientBatchID }}",
  "group id": "{{ .GroupID }}",
  "file size": "{{ .FileSizeBytes }}"
}

The above example has a Sama Project already set up with inputs "name"(string), "url"(URL), "client batch id"(string), "group id"(string), and "file size"(string). The mapping json will be saved into .mapping.json.gotmpl in your current working directory.

Advanced configuration of the mapping json

The mapping json, mapping.json.gotmpl, contains your Sama Project inputs and values that will be sent during task creation. The values that you see in {{ }} are special variables used by the CLI and are replaced during task creation. The list of special variables are:

"{{ .BaseName }}" - gets replaced by the asset's name, e.g. image001.png.
"{{ .AssetFolderName }}" - gets replaced by the name of the containing folder. For example, the folder in s3 containing the asset.
"{{ .URL }}" - gets replaced by the asset's URL path in Sama's S3, e.g. https://sama-client-assets.s3.amazonaws.com/123/assets_batch001/image001.png
"{{ .ClientBatchID }}" - gets replaced by the string specified with the --client-batch-id flag
"{{ .GroupID }}" - gets replaced by a unique groupID when using the --group-size flag
"{{ .FileSizeBytes }}" - gets replaced by the asset's file size

When you call sama init, the CLI will do it's best to automatically use the special variables depending on your Sama Project's inputs.

If you have an input called "name", "asset name", or "file name", the CLI will automatically insert "{{ .BaseName }}" as its value.
If you have an input type of "URL", the CLI will automatically insert "{{ .URL }}" as its value.
If you have an input type that is marked as "Client Batch ID", the CLI will automatically insert "{{ .ClientBatchID }}" as its value.
If you have an input type that is marked as "Task Group ID", the CLI will automatically insert "{{ .GroupID }}" as its value.
If you have an input called "size", "asset size", or "file size", the CLI will automatically insert "{{ .FileSizeBytes}}" as its value.

If needed, modify mapping.json.gotmpl so that the proper data is sent during task creation. Examples of the mapping json are given below.