Device Scripting

Overview

Scripting is a feature that allows you to run a script unattended (written in any interpreted language you have installed on your Operating System) on any number of devices with a Linux or Windows based operating system.

This is useful when you have a repetitive action that you would like to perform on one or more devices.

These examples are for graphQL API scripting and do not apply to legacy.app.remote.it UI scripting. legacy.app.remote.it is deprecated and you should use this method.

Creating Scripts

Remote.It allows you to write scripts in any language your host operating system supports because the script is run just like any other executable script on your machine. This means you can write in bash, Python, Ruby, Node, etc., assuming you have the interpreter installed on your system. Scripts are executed as root.

Example shell scripts can be found at our github repository.

https://link.remote.it/github/scripts

Scripts can have arguments which you can pass. Arguments can be created by placing commented lines like this in your code:

# The following defines arguments for selecting a file, entering a string or selecting from a list of strings:
# These arguments are optional and can be removed if not needed.
# Once defined their values can be accessed  via their name in the script (e.g., $textFile, $url, $name, $action)
# <arguments>, <type>, <name>, <prompt>, <option1>, <option2>, ... 
# r3_argument, FileSelect, textFile, Select File, .txt
# r3_argument, StringEntry, url, Enter Fully-Qualified URL
# r3_argument, StringEntry, name, Enter a Name
# r3_argument, StringSelect, action, Choose Action, ADD, REMOVE

These arguments can then be used as environment variables in you code. See script examples for usage.

Uploading a Script

You can upload files using a multi form post to be run as a script or a file to be used by your scripts. Setting the executable flag will determine if the file can be run as a script (see scripting api docs).

curl --request POST \
  --url https://api.remote.it/graphql/v1/file/upload \
  --header 'Authorization: ' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Date: Thu, 23 May 2024 00:32:27 GMT' \
  --header 'Host: api.remote.it' \
  --header 'User-Agent: insomnia/8.5.1' \
  --form file=@/Users/ebowers/Documents/remoteit/scripting/final/script_example_no_args.sh \
  --form executable=true \
  --form 'shortDesc=New Script Example No Args' \
  --form 'longDesc=This is a new script that has no args as an example'

You must be the account owner or if you belong to an organization, an admin on the account to upload a file.

Files must be able to be uploaded in 30 seconds. If you need to have larger files, consider hosting at another location such as S3 and having your script fetch them.

Running a Script

You can run your recent uploaded script with a graphql mutation.

View files

query GetFiles {
                login {
                    account {
                        id
			files  {
				id
				name
				shortDesc
				longDesc
				lastVersion {
					id
					version
				}
				executable
			}
                    }
                }
            }

Run Script without arguments

mutation execute {
	startJob(
		deviceIds: ["80:00:00:00:01:22:37:AE"],
    fileId: "b0fd8a0f-2850-4be3-88cd-b554551e4dd4"
  )
}

Run Script with arguments

mutation execute {
	startJob(
		deviceIds: ["80:00:00:00:XX:XX:XX:XX"],
    		fileId: "5539cee9-3bea-4c04-add6-bd7c2aff12df"
		arguments: [
			{
				name: "url"
				value: "https://remote.it"
			},
			{
				name: "textFile"
				value: "6b69b085-5507-468f-93c2-d64cdd40eb8e"
			},
			{
				name: "name"
				value: "RemoteIt"
			},
			{
				name: "action"
				value: "Add"
			}
		]
  )
}

Get Script/Job Status

You can query for scripts status using the api. Attributes and Status set during the script will appear in the attribute list for the job.

query GetJobs {
                login {
			account {																			jobs (size: 10, minDate: "2024-04-09T19:00:00") {
				hasMore
				total
				items {
					id													created
 					status
					fileVersion {
						id
						file {
							id
							name
						}
					}
					jobDevices {
						id
						device {
							id
							name
						}
						attributes {
							key
							value
						}
						status
					}

				}
			}
		}
	}

API documentation