conduit
Command and control made easy.
Documentation Scripting Download Code

PLATFORM

$system.PLATFORM is a variable which contains the platform name of the system. It will contain either darwin, linux, or windows. to it.


if ($system.PLATFORM == "linux") {
  // ...
}

ARCH

$system.ARCH is a variable which contains the currently archetecture. Values will be amd64 or 386


if ($system.ARCH == "amd64") {
  // ...
}

env(name)

$system.env will return the value of an environment variable passed to it.

Arguments
  • name (string) - The name of the environment variable to retrieve.
Return value

(string) - The value of the environment variable. 


var java = $system.env("JAVA_HOME");

expand(template)

$system.expand expands environment variables from a template string. Any variable can be included in the string using "{}". A string is returned with these placeholders replaced with the appropriate values.

Arguments
  • template (string) - A template string to expand.
Return value

(string) - The template string is returned with the placeholders replaced with the appropriate environment variables.


var tpl = "{JAVA_HOME}/java -jar test.jar"
var cmd = $system.expand(tpl);
$system.shell(cmd);

currentUser

Returns an object with information about the current user.

Arguments

None

Return value

(object) - An object with the following propreties:

  • name (string) - The name of the current user.
  • homeDir (string) - The path to the current user's home directory.
  • uid (string) - The current user's identifier.
  • gid (string) - The current user's group id.
  • username (string) - The current user's username.

var user = $system.currentUser();
var path = $file.join(user.homeDir, "test.txt");
$file.write(path, "hello");

execute(cmd, args, noerror)

$system.execute will execute a process with the given arguments. In unix environments this process runs as a child of conduit itself. This command will block until the process exits.

Arguments
  • cmd (string) - The path to the binary to execute.
  • args (array) - An array of arguments to execute
  • throw (bool) - (default: true) - If true a javascript error will be thrown if the process returns an error.
Return value

None


var path = "/opt/bin/myutil";
try {
  $system.execute(path, []);
  $(true) // return the status of the process.
} catch (err) {
  $(err) // return the error message.
}

exceuteAndRead(cmd,args)

$system.executeAndRead will execute a process in the same way as $system.execute. The full output is returned after the process exits.

Arguments
  • cmd (string) - The path to the binary to execute.
  • args (array) - An array of arguments to execute
Return value

(string) - The output from the process.


var path = "/usr/bin/ruby";
var ver = $system.executeAndRead(path,
  ["--version"]);
$(ver); // Send back the version

detach(cmd,args)

$system.detach will run a process similar to $system.execute. Instead of running the application as a child process, it will launch it as a seperate process. Allowing it to run independent of Conduit. This function returns immediately after executing and does not wait for it to complete.

Arguments
  • cmd (string) - The path to the binary to execute.
  • args (array) - An array of arguments to execute
Return value

None


var path = "/opt/bin/somelongprocess";
$system.detach(path, []);

shell(cmd)

$system.shell executes a given command string from a shell environment.

Arguments
  • cmd (string) - A command string to execute.
Return value

(int) - Returns the exit code from the command.


var cmd = "cd /mnt/current && bundle install";
var code = $system.shell(cmd);
$(code == 0) // send back the result

kill(process)

$system.kill will force quit a given process, by process name.

Arguments
  • process (string) - The name of the process to kill.
Return value

None


var path = "/usr/bin/puma";
var config = "/mnt/current/config";
$system.kill("puma");
$system.detach(path, ["-c", config]);

get(url)

$http.get makes a web request against a remote server and returns the servers response. It can be used to communicate with web APIs or request information from a web resource.

Arguments
  • url (string) - The url to request.
Return value

(string) - Returns a string value contianing the response text from the request


var url = "http://...";
var data = $http.get(url);
// data  is now a string containing the content
// of the response.

post(url, data, contentType)

$http.post makes a web request against a remote server and returns the servers response. It can be used to communicate with web APIs or request information from a web resource.

Arguments
  • url (string) - The url to request.
  • post data (string) - Data to be posted to the server during the request.
  • content type (string) -A content type for the post data. If a value is specified it will be used in the request header to set the ContentType.
Return value

(string) - Returns a string value contianing the response text from the request


var url = "http://...";
var data = {
  firstName: "Alice",
  lastName: "Alan",
  phoneNumber: "5555555555"
};

var ct = "application/json";
var dataStr = JSON.stringify(data);
var resStr = $http.post(url, dataStr, ct);
var res = JSON.parse(resStr);

download(url, target)

$http.download will download a file from a web server and save it to the target path specified.

Arguments
  • url (string) - The url of the file to download.
  • target (string) - The target path to save the file to.
Return value

None


var url = "http://...";
var localFile = "/tmp/installer.tar.gz";
$http.download(url, localfile);

eachFile(pattern, callback)

$file.eachFile function will collect all files that match a glob pattern and call the callback once for each file.

Arguments
  • pattern (string) - A glob pattern to match files against.
  • callback (function) - A callback function that accepts a single variable for the file path.
Return value

None

            
var logEP = "http://...";
var pattern = "/log/app/*.log";
$file.eachFile(pattern,function(f) {
  $http.upload(f, logEP);
});

eachLine(fp, fn)

$file.eachLine will open a file and execute the given function once for each line of the file (as noted by "\n"). The function will be passed the text of the line as an arguemnt. pattern and call the callback once for each file.

Arguments
  • fp (string) - The path to the file to process.
  • fn (function) - A function which will be called for every line in the file. It will be passed a single variable containing the lines text (without a new line character).
Return value

None

            
var fp = "...";
var count = 0;
$file.eachLine(fp, function(line) {
  var count += parseInt(line);
});

exists(path)

$file.exists checks the existance of a path.

Arguments
  • path (string) - The path to check. This can be either a file or a directory.
Return value

(bool) - Returns true if the path exists.


var path = "app.log";
if ($file.exists(path)) {
  $file.delete(path);
}

info(path)

$file.info returns information about a path.

Arguments
  • path (string) - The path to check. This can be either a file or a directory.
Return value

(object) - An object containing the following fields:

  • size (int) - The file's size in bytes.
  • isDir (bool) - True if the path is a directory.
  • name (string) - The base name of the file.
  • lastModified (int) - The files last modified time, in unix time.

var path = "app.log";
if ($file.exists(path)) {
  $file.delete(path);
}

join(tokens)

$file.join provides a cross platform way to assemble file paths from an array of path tokens.

Arguments
  • tokens (array) - An array of path tokens each token will be joined by a platform specific directory seperator.
Return value

(string) The assembled path.


var user = $system.currentUser();
var home = user.homeDir;
var appFolder = "app";
var logFile = "app.log";
var path = $file.join(home, appFolder, logFile);
$file.move(path, "backup.log");

readString(path)

$file.readString eads an entire file into a string.

Arguments
  • path (string) - The path to the file to read.
Return value

(string) - The contents of the file.


var data = $file.readString("app.log");
$(data);

size(path)

Returns the disk usage of a given file.

Arguments
  • path (string) - The path to a file.
Return value

(int) The size of the file on disk.


var path = "app.log";
var size = file.size(path);
$(size);

write(path, content)

$file.write will write data to a local file. If the file exists it will be appended to. If it does not exist it will be created.

Arguments
  • filepath (string) - The path to the file to write to.
  • content (string) - The content to write.
Return value

None


var appPath = $system.env("APP_PATH");
var gemfile = $file.join(appPath, "gemfile");
$file.write(gemfile, "gem 'mygem'");
var cmd = $system.expand(
  "cd {APP_PATH} && bundle");
$system.shell(cmd);

copy(source,destination)

$file.copy will copy a file from one location to another. A javascript error will be thrown if the destination already exists.

Arguments
  • source (string) - The source file to copy.
  • destination (string) - The destination to copy to.
Return value

None


var path = "app.log";
var dest = "backup.log";
try {
  $file.copy(path, dest);
  $(true);
} catch (err) {
  $(err);
}

move(source, destination)

$file.move will move a file from its current location to the destination path. It will throw a javascript error if the destination file already exists.

Arguments
  • source (string) - The source file to move.
  • destination (string) - The destination path to move the file to.
Return value

None


var path = "app.log";
var dest = "backup.log";
try {
  $file.move(path, dest);
  $(true);
} catch (err) {
  $(err);
}

delete(path)

Deletes a file at the given path.

Arguments
  • path (string) - The path to the file to delete.
Return value

None


$file.delete("backup.log");

mkdir(path)

$file.mkdir will create all directories that do not exist in the given path.

Arguments
  • path (string) - The path to create.
Return value

None


var path = "/var/logs/myapp/";
var lp = $file.join([path, "app.log"]);
$file.write(lp, "some information");

tempFile

$file.tempFile will return a filepath to a randomly named file in the systems temporary location.

Arguments

None

Return value

(string) The filepath to a temporary file.


var tmp = $file.tempFile();
var url = "...";
$http.download(url, tmp);

tempFolder

$file.tempFile will return a filepath to a randomly named directory in the systems temporary location.

Arguments

None

Return value

(string) The path to a temporary folder.


var url = "...";
var tmp = $file.tempFolder();
var tarFP = $file.join(tmp, "down.tar");
$http.download(url, tmp);
$tar.decompress(tarFP, tmp);

base(path)

$file.base will return the base directory for a path, such as the filename or last folder name.

Arguments
  • path (string) - The path to process.
Return value

(string) The path to the base folder.


var path = "/home/user/test.txt";
var fp = $file.base(path); // test.txt
var newP = "/tmp/";
$file.move(fp, newP);

dir(path)

$file.dir will return the parent directory for the path.

Arguments
  • path (string) - The path to process.
Return value
  • (string) - The path to the parent directory folder.

var path = "/home/user/test.txt";
var dir = $file.dir(path);
var newP = $file.join(dir, "test2.txt");

ext(path)

$file.ext will return the file extension if it exists for the given path.

Arguments
  • path (string) - The path to process.
Return value
  • (string) - The file extension or an empty string.

var path = "/home/user/test.txt";
if ($file.ext(path) != "txt")  {
  $("bad file type");
}

compress(path, zipfile)

$zip.compress will compress all files recursively in the path into the destination zipfile.

Arguments
  • path (string) - The path to compress. If the path is a directory all files and sub directories will be compressed.
  • zipfile (string) - The path to the destination zipfile.
Return value

None


try {
  var path = "/var/log/app/*.log";
  var ep = "http://...";
  var zf = "/tmp/logZip.zip";
  $zip.compress(path, zf);
  $http.upload(ep, zf);
  $(true);
} catch (err) {
  $(err);
} finally {
  if ($file.exists(zf)) {
    $file.delete(zf);
  }
}

decompress(zipfile, path)

$zip.decompress will unzip a zipfile into the given path.

Arguments
  • zipfile (string) - The path to the zipfile to extract.
  • path (string) - The directory to unzip the files into.
Return value

None


var ep = "http://...";
var zf = "/tmp/app.zip";
try {
  $http.download(ep, zf);
  $zip.decompress(zf, "/opt/app/");
  $(true);
} catch (err) {
  $(err);
} finally {
  if ($file.exists(zf)) {
    $file.delete(zf);
  }
}

compress(source, tarfile)

$tar.compress will compress all files recursively in the source folder into the specified tarfile.

Arguments
  • source (string) The source folder to compress.
  • destination (string) The tarfile to create.
Return value

None


$local = function() {
  var codepath = "...";
  var assetPath = "...";
  $tar.compress(codepath, assetPath);
}
var deployPath = "...";
$tar.decompress($asset.filepath, deployPath);

decompress(tarfile, destination)

$tar.decompress will extract all files in the specified tar file, rooted in the destination folder. Sub paths will be automatically created and extracted into.

Arguments
  • tarfile (string) The file path to the .tar file.
  • destination (string) A destination folder to extract files to.
Return value

None


$local = function() {
  var codepath = "...";
  var assetPath = "...";
  $tar.compress(codepath, assetPath);
}
var deployPath = "...";
$tar.decompress($asset.filepath, deployPath);

compress(source, dst)

$gzip.compress a single file using the gzip algorithm

Arguments
  • source (string) A path to the source file.
  • dst (string) A path with filename for the destination file.
Return value

None


var gzFP = "somefile.tar.gz";
var tarFP = "somefile.tar";
var sourceFolder = "...";
$tar.compress(sourceFolder, tarFP);
$gzip.compress(tarFP, gzFP);
$file.delete(tarFP);

decompress(source, dst)

$gzip.decompress will decompress a gzip file

Arguments
  • source (string) A path to the gzip file.
  • dst (string) A path with filename for the destination file.
Return value

None


var gzFP = "somefile.tar.gz";
var tarFP = "somefile.tar";
var destFolder = "...";
$gzip.decompress(gzFP, tarFP);
$tar.decompress(tarFP, destFolder);
$file.delete(tarFP);

$(message)

The "$" function is used to respond with back with information. Any variable passed to it will be converted to a string (using toString) and sent back to the server. These are then stored as execution responses and can be reported.

This function is used to to report the status of a script's execution, report back error messages, or used to gather information from the client.

Arguments
  • message (any) - The data to pass back to the server.
Return value

None


try {
  var cmd = "/usr/bin/du";
  var du = $system.executeAndRead(cmd, ["-h"])
  $(du);
} catch (err) {
  $(false);
}

$local - function

In some workflows it might be useful to perform local tasks before deploying the script. This can be helpful for build deployments, or similar tasks. $local can be set to a function literal. This function will be executed locally before sending the script to the clients.


$local = function() {
  $system.shell("build_script.sh");
  $systen.shell("upload_script.sh");
};
$http.download("...");
// ... more stuff
$(true)

$agent(name, fn)

$agent will pass the function to the given agent. For more information on setting up agents see Conduit Agents. The passed function will be sent to the agent and executed.

Arguments
  • name (string) - The name of the agent as set in the config file.
  • fn (function) - The function to pass to the agent.
Return value

None


$agent("local", function() {
  $system.execute("notepad.exe");
});

filepath

$asset.filepath is a string value with the filepath to the script's asset.


if $asset.exists() {
  $tar.decompress($asset.filepath, "...");
}

exists

$asset.exists will check if an asset was deployed with the script.

Arguments

None

Return value
  • (bool) - true if an asset was downloaded with the script.

if $asset.exists {
  // process asset
}