Tachyon Filesystem
The Tachyon platform organizes data into named Filesystem s. A Filesystem  is the medium that stores and distributes data pushed into the Tachyon platform. A Filesystem  functions very much like a traditional Unix-based filesystem, with the same file and folder semantics, paths delineated using forward slashes, and functionality like making, copying, moving, and removing files and folders. In order to manipulate a Filesystem , a host has to connect to the Filesystem  using a Filesystem  ID (FID) and a Filesystem -specific API key. Currently, we only support creating Filesystem s and seeing FIDs/API Keys using the Web Administration Dashboard.

In this guide, we will walk you through the main concepts in the Filesystem  library and provide a reference.
You can also find the getting started guide here
If you're looking to read about how your transfer stays safe, check out our security features
Authenticating and Instantiating a Filesystem
new Filesystem(String FILESYSTEM_ID, String API_TOKEN)
Tachyon provides APIs for manipulating an instance of a Filesystem   through the form of a Filesystem  object. Currently, there are libraries for Filesystem  available in Node.js, Objective-C, and C++. We also offer a Filesystem  CLI tool in the event that a user wants to manipulate the file system using the command line or through a shell script. The Filesystem  object is consistent across all of the languages as well as the CLI tool, with the same methods, properties, and semantics.
In order for a Tachyon Client to establish a connection to a Tachyon Filesystem, it must be instantiated using the FID and API key for that Filesystem.

These are strings that can be found in the settings for the Filesystem in the Web Administration Dashboard.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/*
authenticate.cpp
$ g++ -o authenticate authenticate.cpp -llibtachyon-dev
*/
#include <iostream>
#include <cstdlib>

// Download the C++ static library and header files from
// https://trytachyon.com/download
#include "tachyon.hpp"

int
main() {
// Find your Filesystem ID and API Token at https://app.trytachyon.com/
// and set the environment variables.
const char * fid = getenv("FILESYSTEM_ID");
const char * key = getenv("API_KEY");

Tachyon::Filesystem
client(fid, key);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
COMING SOON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Install the Tachyon CLI tool using homebrew:
# $ brew install tachyon# Find your Filesystem ID and API Token at https://app.trytachyon.com/# and set the environment variables.

tachyon filesystem:authenticate $FILESYSTEM_ID $API_TOKEN = process.env.API_TOKEN;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Install the Node.js library from
// https://www.npmjs.com/package/tachyon
// using npm: $ npm i tachyon
import { Filesystem } from 'tachyon-transfer';

// Find your Filesystem ID and API Token at https://app.trytachyon.com/
// and set the environment variables.

const FILESYSTEM_ID = process.env.FILESYSTEM_ID;
const API_TOKEN = process.env.API_TOKEN;

const client = new Filesystem(FILESYSTEM_ID, API_TOKEN);
Params:

API_TOKEN

The API token used to authenticate access to a Tachyon Filesystem specified by FILESYSTEM_ID, represented as a 20 character string, e.g. ABCDEfghij12345!@#$%
Type: String
Required

FILESYSTEM_ID

The ID of the Tachyon Filesystem to perform operations on, represented as a 16-octet UUID string, e.g. 123e4567-e89b-12d3-a456-426614174000
Type: String
Required
Errors:

ERR_UNAUTHORIZED

API_TOKEN or FILESYSTEM_IDare not valid
Uploads
function upload(String LOCAL_PATH, String REMOTE_PATH, Boolean REPLACE=TRUE)
The Tachyon Client provides APIs for uploading arbitrarily named, and sized files and folders.
The upload method requires two parameters, LOCAL_PATH and REMOTE_PATH and an optional third parameter REPLACE. Both LOCAL_PATH and REMOTE_PATH are strings that specify a file or directory, in the local filesystem and Tachyon Filesystem respectively. REPLACE is a boolean specifying whether to replace files or folders in the Filesystem; its default value is true.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/*
   upload.cpp
   $ g++ -o upload upload.cpp -llibtachyon-dev  
*/

#include <iostream>
#include <cstdlib>

// Download the C++ static library and header files from
// https://trytachyon.com/download
#include "tachyon.hpp"

int
main() {
  // Find your Filesystem ID and API Token at https://app.trytachyon.com/   // and set the environment variables.
  
const char * fid = getenv("FILESYSTEM_ID");
  
const char * key = getenv("API_KEY");

  Tachyon::Filesystem
client(fid, key);
  
client.upload("/tmp/example.txt", "/remoteFolder/", true)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
COMING SOON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Install the Tachyon CLI tool using homebrew:
# $ brew install tachyon


# Find your Filesystem ID and API Token at https://app.trytachyon.com/
# and set the environment variables.

tachyon authenticate $FILESYSTEM_ID $API_TOKEN

tachyon upload --replace /tmp/example.txt /remoteFolder/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Install the Node.js library from https://www.npmjs.com/package/tachyon
// using npm: $ npm i tachyon
import { Filesystem } from 'tachyon-transfer';

// Find your Filesystem ID and API Token at https://app.trytachyon.com/
// and set the environment variables.

const FILESYSTEM_ID = process.env.FILESYSTEM_ID;
const API_TOKEN = process.env.API_TOKEN;

const client = new Filesystem(FILESYSTEM_ID, API_TOKEN);
client.upload("mylocalpath/mylocalfile" , "filesystem/filesystemfolder");

Params:

LOCAL_PATH
A string specifying the location of the file or directory to be uploaded from the host filesystem
Type: String
Required

REMOTE_PATH
A string specifying the location on the Tachyon Filesystem that the file specified by LOCAL_PATH  will be stored
Type: String
Required

REPLACE

A boolean indicating whether or not to replace files and directories with the same name. Defaults to true
Type: Boolean
Optional
Default Value: True
Errors

ERR_DOES_NOT_EXIST

LOCAL_PATH and  REMOTE_PATH both specify files, but the file names are not the same
REMOTE_PATH does not exist in the specified Tachyon Filesystem
LOCAL_PATH does not exist ion the host file

ERR_INVALID_OPERATION

LOCAL_PATH specifies a directory and REMOTE_PATH specifies a file; REPLACE is set to false,  REMOTE_PATH specifies a file

ERR_REPLACE

REPLACE is set to false, REMOTE_PATH specifies a folder, and file(s)/folder(s) in LOCAL_PATH exist inREMOTE_PATH
Downloads
function download(String LOCAL_PATH, String REMOTE_PATH, Boolean REPLACE=TRUE)
The Tachyon Filesystem provides APIs for downloading arbitrarily named, and sized files and folders.
The download method requires two parameters, LOCAL_PATH and REMOTE_PATH and an optional third parameter REPLACE. Both LOCAL_PATH and REMOTE_PATH are strings that specify a file or directory, in the local filesystem and Tachyon Filesystem respectively. REPLACE is a boolean specifying whether to replace files or folders in the local machine; its default value is true.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/*
  download.cpp
  $ g++ -o download download.cpp -llibtachyon-dev
*/

#include <iostream>
#include <cstdlib>

// Download the C++ static library and header files from
// https://trytachyon.com/download
#include "tachyon.hpp"

int
main() {
  // Find your Filesystem ID and API Token at https://app.trytachyon.com/
  // and set the environment variables.
  
const char * fid = getenv("FILESYSTEM_ID");
  
const char * key = getenv("API_KEY");

  Tachyon::Filesystem
client(fid, key);
  client.
download("/tmp/", "/remoteFolder/", true)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
COMING SOON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Install the Tachyon CLI tool using homebrew:
# $ brew install tachyon


# Find your Filesystem ID and API Token at https://app.trytachyon.com/
# and set the environment variables.

tachyon authenticate $FILESYSTEM_ID $API_TOKEN

tachyon download --replace /tmp/example.txt /remoteFolder/



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Install the Node.js library from https://www.npmjs.com/package/tachyon
// using npm: $ npm i tachyon
import { Filesystem } from 'tachyon-transfer';

// Find your Filesystem ID and API Token at https://app.trytachyon.com/
// and set the environment variables.

const FILESYSTEM_ID = process.env.FILESYSTEM_ID;
const API_TOKEN = process.env.API_TOKEN;

const client = new Filesystem(FILESYSTEM_ID, API_TOKEN);
client.download("mylocalpath/mylocalfile" , "filesystem/filesystemfolder");

Params:

LOCAL_PATH

LOCAL_PATH is a string specifying the location of the file or directory to be uploaded from the REMOTE_PATH
Type: String
Required

REMOTE_PATH

A string specifying the file or folder on the Tachyon Filesystem that should be downloaded
Type: String
Required

REPLACE

A boolean indicating whether or not to replace files and directories with the same name. Defaults to true
Type: Boolean
Optional
Default Value: TRUE
Errors

ERR_DOES_NOT_EXIST

LOCAL_PATH and  REMOTE_PATH both specify files, but the file names are not the same; REMOTE_PATH does not exist in the specified Tachyon Filesystem

ERR_INVALID_OPERATION

REMOTE_PATH specifies a directory and LOCAL_PATH specifies a file; REPLACE is set to false,  LOCAL_PATH specifies a file

ERR_REPLACE

REPLACE is set to false, REMOTE_PATH specifies a folder, and file(s)/folder(s) in REMOTE_PATH exist inLOCAL_PATH
List
function list(String REMOTE_PATH)
The Tachyon Filesystem provides APIs for listing files in similar style to UNIX systems.
List takes a single required parameter, REMOTE_PATH, that specifies a path on the Tachyon Filesystem. REMOTE_PATH is of type string. If REMOTE_PATH specifies a file in the Filesystem, list will return information about that file. If REMOTE_PATH  is a directory, list  will return an Array -like object with information about the files and folders inside of the directory specified by REMOTE_PATH.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/*
   list.cpp
   $ g++ -o list list.cpp -llibtachyon-dev
*/

#include <iostream>
#include <cstdlib>

// Download the C++ static library and header files from
// https://trytachyon.com/download
#include "tachyon.hpp"

int
main() {
   // Find your Filesystem ID and API Token at https://app.trytachyon.com/
   // and set the environment variables.
   
const char * fid = getenv("FILESYSTEM_ID");
   
const char * key = getenv("API_KEY");

   Tachyon::Filesystem
client(fid, key);
   std::vector<string> files = client.
list("/remoteFolder/");
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
COMING SOON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Install the Tachyon CLI tool using homebrew:
# $ brew install tachyon


# Find your Filesystem ID and API Token at https://app.trytachyon.com/
# and set the environment variables.

tachyon authenticate $FILESYSTEM_ID $API_TOKEN

tachyon list /
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Install the Node.js library from https://www.npmjs.com/package/tachyon
// using npm: $ npm i tachyon
import { Filesystem } from 'tachyon-transfer';

// Find your Filesystem ID and API Token at https://app.trytachyon.com/
// and set the environment variables.

const FILESYSTEM_ID = process.env.FILESYSTEM_ID;
const API_TOKEN = process.env.API_TOKEN;

const client = new Filesystem(FILESYSTEM_ID, API_TOKEN);

const arr = client.list("/filesystem/filesystemfolder");
const.log(arr); // ['/', '/testDir1']
Params:
REMOTE_PATH
A string specifying the location on the Filesystem. The list  method will enumerate the files and folders in this location if REMOTE_PATH is a directory, and will return a single file name if REMOTE_PATH  is a file
Type: String
Required
Errors

ERR_DOES_NOT_EXIST

REMOTE_PATH does not exist in the specified Tachyon Filesystem
Make Directory
function makeDirectory(String REMOTE_PATH)
The Tachyon Filesystem provides APIs for making directories in similar style to UNIX systems.
makeDirectory takes a single required parameter, REMOTE_PATH, that specifies a path to create on the Tachyon Filesystem, similar to the mkdir shell command. The makeDirectory method employs a recursive strategy, making all of the directories in a path that do not exist on the Filesystem. If the directory named already exists the method will not replace that directory.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/*
   makeDirectory.cpp
   $ g++ -o makeDirectory makeDirectory.cpp -llibtachyon-dev
*/

#include <iostream>
#include <cstdlib>

// Download the C++ static library and header files from
// https://trytachyon.com/download
#include "tachyon.hpp"

int
main() {
   // Find your Filesystem ID and API Token at https://app.trytachyon.com/
   // and set the environment variables.
   
const char * fid = getenv("FILESYSTEM_ID");
   
const char * key = getenv("API_KEY");

   Tachyon::Filesystem client(fid, key);
   client.
makeDirectory("/remoteFolder/");
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
COMING SOON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Install the Tachyon CLI tool using homebrew:
# $ brew install tachyon


# Find your Filesystem ID and API Token at https://app.trytachyon.com/
# and set the environment variables.

tachyon authenticate $FILESYSTEM_ID $API_TOKEN

tachyon
makeDirectory /testDir/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Install the Node.js library from https://www.npmjs.com/package/tachyon
// using npm: $ npm i tachyon
import { Filesystem } from 'tachyon-transfer';

// Find your Filesystem ID and API Token at https://app.trytachyon.com/
// and set the environment variables.

const FILESYSTEM_ID = process.env.FILESYSTEM_ID;
const API_TOKEN = process.env.API_TOKEN;

const client = new Filesystem(FILESYSTEM_ID, API_TOKEN);

client.makeDirectory(
  "filesystem/filesystemexistngfolder/filesystemnewfoldername");
Params:
REMOTE_PATH
The path to create in the Tachyon Filesystem, delineated by forward slashes. If any of the directories in the path do not exist, they will also be created
Type: String
Required
Errors

ERR_REPLACE

REMOTE_PATH already exists Tachyon Filesystem
Remove
function remove(String REMOTE_PATH, Boolean RECURSIVE=TRUE)
The Tachyon Filesystem allows for the removal of files and folders from the Tachyon Filesystem, using the recursive strategy.
The remove  method accepts a single required parameter, REMOTE_PATH , that specifies the path on the Tachyon Filesystem to remove, and a single optional parameter, RECURSIVE, which specifies if the recursive strategy should be employed when removing nonempty directories in the Filesystem.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/*
   remove.cpp
   $ g++ -o remove remove.cpp -llibtachyon-dev
*/

#include <iostream>
#include <cstdlib>

// Download the C++ static library and header files from
// https://trytachyon.com/download
#include "tachyon.hpp"

int
main() {
   // Find your Filesystem ID and API Token at https://app.trytachyon.com/
   // and set the environment variables.
   
const char * fid = getenv("FILESYSTEM_ID");
   
const char * key = getenv("API_KEY");

   Tachyon::Filesystem
client(fid, key);
   client.
remove("/remoteFolder/", true);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
COMING SOON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Install the Tachyon CLI tool using homebrew:
# $ brew install tachyon


# Find your Filesystem ID and API Token at https://app.trytachyon.com/
# and set the environment variables.

tachyon authenticate $FILESYSTEM_ID $API_TOKEN

tachyon
remove --recursive /testDir/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Install the Node.js library from https://www.npmjs.com/package/tachyon
// using npm: $ npm i tachyon
import { Filesystem } from 'tachyon-transfer';

// Find your Filesystem ID and API Token at https://app.trytachyon.com/
// and set the environment variables.

const FILESYSTEM_ID = process.env.FILESYSTEM_ID;
const API_TOKEN = process.env.API_TOKEN;

const client = new Filesystem(FILESYSTEM_ID, API_TOKEN);

client.remove("/testDir/" , true);
Params:
REMOTE_PATH
The location to remove on the Tachyon Filesystem; can be either a single file or a directory. If the directory is not empty, the RECURSIVE flag must be set to true
Type: String
Required
RECURSIVE
Indicates whether or not to recursively remove all sub-directories and files in a nonempty directory specified by REMOTE_PATH
Type: String
Required
Errors

ERR_DOES_NOT_EXIST

REMOTE_PATH does not exist in the specified Tachyon Filesystem


ERR_NONEMPTY
RECURSIVEis set to false, and REMOTE_PATH is a non-empty directory in the Tachyon Filesystem