<commit_before>---
layout: global
title: Command Line Interface
group: Features
priority: 0
---

Tachyon's command line interface provides users with basic file system operations. You can invoke
the command line utility using:

```bash
$ ./bin/tachyon tfs
```

All "path" variables in tfs commands should start with

    tachyon://<master node address>:<master node port>/<path>

Or, if no header is provided, the default hostname and port (set in the env file) will be used.

    /<path>

## Wildcard Input

Most of the commands which require path components allow wildcard arguments for ease of use. For
example:

```bash
$ ./bin/tachyon tfs rm /data/2014*
```

The example command would delete anything in the `data` directory with a prefix of `2014`.

Note that some shells will attempt to glob the input paths, causing strange errors (Note: the number
21 could be different and comes from the number of matching files in your local filesystem):

```
rm takes 1 arguments,  not 21
```

As a work around, you can disable globbing (depending on your shell, for example `set -f`) or by
escaping wildcards, for example:

```bash
$ ./bin/tachyon tfs cat /\\*
```
Note the double escape, this is because the shell script will eventually call a java program which
should have the final escaped parameters (cat /\\*).

# List of Operations

<table class="table table-striped">
  <tr><th>Operation</th><th>Syntax</th><th>Description</th></tr>
  <tr>
    <td>cat</td>
    <td>cat "path"</td>
    <td>Print the content of the file to the console.</td>
  </tr>
  <tr>
    <td>chgrp</td>
    <td>chgrp "group" "path"</td>
    <td>Change the group of the directory or file.</td>
  </tr>
  <tr>
    <td>chgrpr</td>
    <td>chgrpr "group" "path"</td>
    <td>Recursively change the group of the directory or file.</td>
  </tr>
  <tr>
    <td>chmod</td>
    <td>chmod "permission" "path"</td>
    <td>Change the permission of the directory or file.</td>
  </tr>
  <tr>
    <td>chmodr</td>
    <td>chmodr "permission" "path"</td>
    <td>Recursively change the permission of the directory or file.</td>
  </tr>
  <tr>
    <td>chown</td>
    <td>chown "owner" "path"</td>
    <td>Change the owner of the directory or file.</td>
  </tr>
  <tr>
    <td>chownr</td>
    <td>chownr "owner" "path"</td>
    <td>Recursively change the owner of the directory or file.</td>
  </tr>
  <tr>
    <td>copyFromLocal</td>
    <td>copyFromLocal "source path" "remote path"</td>
    <td>Copy the specified file specified by "source path" to the path specified by "remote path".
    This command will fail if "remote path" already exists.</td>
  </tr>
  <tr>
    <td>copyToLocal</td>
    <td>copyToLocal "remote path" "local path"</td>
    <td>Copy the specified file from the path specified by "remote path" to a local
    destination.</td>
  </tr>
  <tr>
    <td>count</td>
    <td>count "path"</td>
    <td>Display the number of folders and files matching the specified prefix in "path".</td>
  </tr>
  <tr>
    <td>du</td>
    <td>du "path"</td>
    <td>Display the size of a file or a directory specified by the input path.</td>
  </tr>
  <tr>
    <td>fileInfo</td>
    <td>fileInfo "path"</td>
    <td>Print the information of the blocks of a specified file.</td>
  </tr>
  <tr>
    <td>free</td>
    <td>free "path"</td>
    <td>Free a file or all files under a directory from Tachyon. If the file/directory is also
    in under storage, it will still be available there.</td>
  </tr>
  <tr>
    <td>getCapacityBytes</td>
    <td>getCapacityBytes</td>
    <td>Get the capacity of the TachyonFS.</td>
  </tr>
  <tr>
    <td>getUsedBytes</td>
    <td>getUsedBytes</td>
    <td>Get number of bytes used in the TachyonFS.</td>
  </tr>
  <tr>
    <td>load</td>
    <td>load "path"</td>
    <td>Load the data of a file or a directory from under storage into Tachyon.</td>
  </tr>
  <tr>
    <td>loadMetadata</td>
    <td>loadMetadata "path"</td>
    <td>Load the metadata of a file or a directory from under storage into Tachyon.</td>
  </tr>
  <tr>
    <td>location</td>
    <td>location "path"</td>
    <td>Display a list of hosts that have the file data.</td>
  </tr>
  <tr>
    <td>ls</td>
    <td>ls "path"</td>
    <td>List all the files and directories directly under the given path with information such as
    size.</td>
  </tr>
  <tr>
    <td>lsr</td>
    <td>lsr "path"</td>
    <td>Recursively list all the files and directories under the given path with information such
    as size.</td>
  </tr>
  <tr>
    <td>mkdir</td>
    <td>mkdir "path1" ... "pathn" </td>
    <td>Create directory(ies) under the given paths, along with any necessary parent directories. Multiple paths separated by spaces or tabs. This
    command will fail if any of the given paths already exist.</td>
  </tr>
  <tr>
    <td>mount</td>
    <td>mount "path" "uri"</td>
    <td>Mount the underlying file system path "uri" into the Tachyon namespace as "path". The "path"
    is assumed not to exist and is created by the operation. No data or metadata is loaded from
    under storage into Tachyon. After a path is mounted, operations on objects under the mounted
    path are mirror to the mounted under storage.</td>
  </tr>
  <tr>
    <td>mv</td>
    <td>mv "source" "destination"</td>
    <td>Move a file or directory specified by "source" to a new location "destination". This command
    will fail if "destination" already exists.</td>
  </tr>
  <tr>
    <td>persist</td>
    <td>persist "path"</td>
    <td>Persist a file or directory currently stored only in Tachyon to the underlying file system.
    </td>
  </tr>
  <tr>
    <td>pin</td>
    <td>pin "path"</td>
    <td>Pin the given file to avoid evicting it from memory. If the given path is a directory, it
    recursively pins all the files contained and any new files created within this directory.</td>
  </tr>
  <tr>
    <td>report</td>
    <td>report "path"</td>
    <td>Report to the master that a file is lost.</td>
  </tr>
  <tr>
    <td>rm</td>
    <td>rm "path"</td>
    <td>Remove a file. This command will fail if the given path is a directory rather than a
    file.</td>
  </tr>
  <tr>
    <td>rmr</td>
    <td>rmr "path"</td>
    <td>Remove a file, or a directory with all the files and sub-directories that this directory
    contains.</td>
  </tr>
  <tr>
    <td>setTtl</td>
    <td>setTtl "time"</td>
    <td>Set the TTL (time to live) in milliseconds to a file.</td>
  </tr>
  <tr>
    <td>tail</td>
    <td>tail "path"</td>
    <td>Print the last 1KB of the specified file to the console.</td>
  </tr>
  <tr>
    <td>touch</td>
    <td>touch "path"</td>
    <td>Create a 0-byte file at the specified location.</td>
  </tr>
  <tr>
    <td>unmount</td>
    <td>unmount "path"</td>
    <td>Unmount the underlying file system path mounted in the Tachyon namespace as "path". Tachyon
    objects under "path" are removed from Tachyon, but they still exist in the previously mounted
    under storage.</td>
  </tr>
  <tr>
    <td>unpin</td>
    <td>unpin "path"</td>
    <td>Unpin the given file to allow Tachyon to evict this file again. If the given path is a
    directory, it recursively unpins all files contained and any new files created within this
    directory.</td>
  </tr>
  <tr>
    <td>unsetTtl</td>
    <td>unsetTtl</td>
    <td>Remove the TTL (time to live) setting from a file.</td>
  </tr>
</table>

# Example Use Cases

## cat
The `cat` command prints the entire contents of a file in Tachyon to the console. This can be
useful for verifying the file is what the user expects. If you wish to copy the file to your local
file system, `copyToLocal` should be used.

For example, when trying out a new computation job, `cat` can be used as a quick way to check the
output:

```bash
$ ./bin/tachyon tfs cat /output/part-00000
```

## chgrp
The `chgrp` command changes the group of the file or directory in Tachyon. Tachyon supports file
authorization with Posix file permission. Group is an authorizable entity in Posix file permission
model. The file owner or super-user can execute this command to change the group of the file or
directory.

For example, `chgrp` can be used as a quick way to change the group of file:
```bash
$ ./bin/tachyon tfs chgrp tachyon-group-new /input/file1
```

## chgrpr
The `chgrpr` command is similar to `chgrp`, but it also recursively changes the group of child file
and directory in Tachyon.

For example, `chgrpr` can be used as a quick way to recursively change the group of directory:
```bash
$ ./bin/tachyon tfs chgrpr tachyon-group-new /input/directory1
```

## chmod
The `chmod` command changes the permission of file or directory in Tachyon. Currently octal modes
is supported: the numerical format accepts three octal digits which refer to permissions for the
file owner, the group and other users. Here is number-permission mapping table:

<table class="table table-striped">
  <tr><th>Number</th><th>Permission</th><th>rwx</th></tr>
  <tr>
    <td>7</td>
    <td>read, write and execute</td>
    <td>rwx</td>
  </tr>
  <tr>
    <td>6</td>
    <td>read and write</td>
    <td>rw-</td>
  </tr>
  <tr>
    <td>5</td>
    <td>read and execute</td>
    <td>r-x</td>
  </tr>
  <tr>
    <td>4</td>
    <td>read only</td>
    <td>r--</td>
  </tr>
  <tr>
    <td>3</td>
    <td>write and execute</td><commit_msg>Update Command-Line-Interface.md<commit_after>---
layout: global
title: Command Line Interface
group: Features
priority: 0
---

Tachyon's command line interface provides users with basic file system operations. You can invoke
the command line utility using:

```bash
$ ./bin/tachyon tfs
```

All "path" variables in tfs commands should start with

    tachyon://<master node address>:<master node port>/<path>

Or, if no header is provided, the default hostname and port (set in the env file) will be used.

    /<path>

## Wildcard Input

Most of the commands which require path components allow wildcard arguments for ease of use. For
example:

```bash
$ ./bin/tachyon tfs rm /data/2014*
```

The example command would delete anything in the `data` directory with a prefix of `2014`.

Note that some shells will attempt to glob the input paths, causing strange errors (Note: the number
21 could be different and comes from the number of matching files in your local filesystem):

```
rm takes 1 arguments,  not 21
```

As a work around, you can disable globbing (depending on your shell, for example `set -f`) or by
escaping wildcards, for example:

```bash
$ ./bin/tachyon tfs cat /\\*
```
Note the double escape, this is because the shell script will eventually call a java program which
should have the final escaped parameters (cat /\\*).

# List of Operations

<table class="table table-striped">
  <tr><th>Operation</th><th>Syntax</th><th>Description</th></tr>
  <tr>
    <td>cat</td>
    <td>cat "path"</td>
    <td>Print the content of the file to the console.</td>
  </tr>
  <tr>
    <td>chgrp</td>
    <td>chgrp "group" "path"</td>
    <td>Change the group of the directory or file.</td>
  </tr>
  <tr>
    <td>chgrpr</td>
    <td>chgrpr "group" "path"</td>
    <td>Recursively change the group of the directory or file.</td>
  </tr>
  <tr>
    <td>chmod</td>
    <td>chmod "permission" "path"</td>
    <td>Change the permission of the directory or file.</td>
  </tr>
  <tr>
    <td>chmodr</td>
    <td>chmodr "permission" "path"</td>
    <td>Recursively change the permission of the directory or file.</td>
  </tr>
  <tr>
    <td>chown</td>
    <td>chown "owner" "path"</td>
    <td>Change the owner of the directory or file.</td>
  </tr>
  <tr>
    <td>chownr</td>
    <td>chownr "owner" "path"</td>
    <td>Recursively change the owner of the directory or file.</td>
  </tr>
  <tr>
    <td>copyFromLocal</td>
    <td>copyFromLocal "source path" "remote path"</td>
    <td>Copy the specified file specified by "source path" to the path specified by "remote path".
    This command will fail if "remote path" already exists.</td>
  </tr>
  <tr>
    <td>copyToLocal</td>
    <td>copyToLocal "remote path" "local path"</td>
    <td>Copy the specified file from the path specified by "remote path" to a local
    destination.</td>
  </tr>
  <tr>
    <td>count</td>
    <td>count "path"</td>
    <td>Display the number of folders and files matching the specified prefix in "path".</td>
  </tr>
  <tr>
    <td>du</td>
    <td>du "path"</td>
    <td>Display the size of a file or a directory specified by the input path.</td>
  </tr>
  <tr>
    <td>fileInfo</td>
    <td>fileInfo "path"</td>
    <td>Print the information of the blocks of a specified file.</td>
  </tr>
  <tr>
    <td>free</td>
    <td>free "path"</td>
    <td>Free a file or all files under a directory from Tachyon. If the file/directory is also
    in under storage, it will still be available there.</td>
  </tr>
  <tr>
    <td>getCapacityBytes</td>
    <td>getCapacityBytes</td>
    <td>Get the capacity of the TachyonFS.</td>
  </tr>
  <tr>
    <td>getUsedBytes</td>
    <td>getUsedBytes</td>
    <td>Get number of bytes used in the TachyonFS.</td>
  </tr>
  <tr>
    <td>load</td>
    <td>load "path"</td>
    <td>Load the data of a file or a directory from under storage into Tachyon.</td>
  </tr>
  <tr>
    <td>loadMetadata</td>
    <td>loadMetadata "path"</td>
    <td>Load the metadata of a file or a directory from under storage into Tachyon.</td>
  </tr>
  <tr>
    <td>location</td>
    <td>location "path"</td>
    <td>Display a list of hosts that have the file data.</td>
  </tr>
  <tr>
    <td>ls</td>
    <td>ls "path"</td>
    <td>List all the files and directories directly under the given path with information such as
    size.</td>
  </tr>
  <tr>
    <td>lsr</td>
    <td>lsr "path"</td>
    <td>Recursively list all the files and directories under the given path with information such
    as size.</td>
  </tr>
  <tr>
    <td>mkdir</td>
    <td>mkdir "path1" ... "pathn" </td>
    <td>Create directory(ies) under the given paths, along with any necessary parent directories. Multiple paths separated by spaces or tabs. This
    command will fail if any of the given paths already exist.</td>
  </tr>
  <tr>
    <td>mount</td>
    <td>mount "path" "uri"</td>
    <td>Mount the underlying file system path "uri" into the Tachyon namespace as "path". The "path"
    is assumed not to exist and is created by the operation. No data or metadata is loaded from
    under storage into Tachyon. After a path is mounted, operations on objects under the mounted
    path are mirror to the mounted under storage.</td>
  </tr>
  <tr>
    <td>mv</td>
    <td>mv "source" "destination"</td>
    <td>Move a file or directory specified by "source" to a new location "destination". This command
    will fail if "destination" already exists.</td>
  </tr>
  <tr>
    <td>persist</td>
    <td>persist "path"</td>
    <td>Persist a file or directory currently stored only in Tachyon to the underlying file system.
    </td>
  </tr>
  <tr>
    <td>pin</td>
    <td>pin "path"</td>
    <td>Pin the given file to avoid evicting it from memory. If the given path is a directory, it
    recursively pins all the files contained and any new files created within this directory.</td>
  </tr>
  <tr>
    <td>report</td>
    <td>report "path"</td>
    <td>Report to the master that a file is lost.</td>
  </tr>
  <tr>
    <td>rm</td>
    <td>rm "path"</td>
    <td>Remove a file. This command will fail if the given path is a directory rather than a
    file.</td>
  </tr>
  <tr>
    <td>rmr</td>
    <td>rmr "path"</td>
    <td>Remove a file, or a directory with all the files and sub-directories that this directory
    contains.</td>
  </tr>
  <tr>
    <td>setTtl</td>
    <td>setTtl "time"</td>
    <td>Set the TTL (time to live) in milliseconds to a file.</td>
  </tr>
  <tr>
    <td>tail</td>
    <td>tail "path"</td>
    <td>Print the last 1KB of the specified file to the console.</td>
  </tr>
  <tr>
    <td>touch</td>
    <td>touch "path"</td>
    <td>Create a 0-byte file at the specified location.</td>
  </tr>
  <tr>
    <td>unmount</td>
    <td>unmount "path"</td>
    <td>Unmount the underlying file system path mounted in the Tachyon namespace as "path". Tachyon
    objects under "path" are removed from Tachyon, but they still exist in the previously mounted
    under storage.</td>
  </tr>
  <tr>
    <td>unpin</td>
    <td>unpin "path"</td>
    <td>Unpin the given file to allow Tachyon to evict this file again. If the given path is a
    directory, it recursively unpins all files contained and any new files created within this
    directory.</td>
  </tr>
  <tr>
    <td>unsetTtl</td>
    <td>unsetTtl</td>
    <td>Remove the TTL (time to live) setting from a file.</td>
  </tr>
</table>

# Example Use Cases

## cat
The `cat` command prints the entire contents of a file in Tachyon to the console. This can be
useful for verifying the file is what the user expects. If you wish to copy the file to your local
file system, `copyToLocal` should be used.

For example, when trying out a new computation job, `cat` can be used as a quick way to check the
output:

```bash
$ ./bin/tachyon tfs cat /output/part-00000
```

## chgrp
The `chgrp` command changes the group of the file or directory in Tachyon. Tachyon supports file
authorization with Posix file permission. Group is an authorizable entity in Posix file permission
model. The file owner or super-user can execute this command to change the group of the file or
directory.

For example, `chgrp` can be used as a quick way to change the group of file:
```bash
$ ./bin/tachyon tfs chgrp tachyon-group-new /input/file1
```

## chgrpr
The `chgrpr` command is similar to `chgrp`, but it also recursively changes the group of child file
and directory in Tachyon.

For example, `chgrpr` can be used as a quick way to recursively change the group of directory:
```bash
$ ./bin/tachyon tfs chgrpr tachyon-group-new /input/directory1
```

## chmod
The `chmod` command changes the permission of file or directory in Tachyon. Currently octal mode
is supported: the numerical format accepts three octal digits which refer to permissions for the
file owner, the group and other users. Here is number-permission mapping table:

<table class="table table-striped">
  <tr><th>Number</th><th>Permission</th><th>rwx</th></tr>
  <tr>
    <td>7</td>
    <td>read, write and execute</td>
    <td>rwx</td>
  </tr>
  <tr>
    <td>6</td>
    <td>read and write</td>
    <td>rw-</td>
  </tr>
  <tr>
    <td>5</td>
    <td>read and execute</td>
    <td>r-x</td>
  </tr>
  <tr>
    <td>4</td>
    <td>read only</td>
    <td>r--</td>
  </tr>
  <tr>
    <td>3</td>
    <td>write and execute</td>
{'fraction_non_alphanumeric': 0.13041375604513702, 'fraction_numerical': 0.0031166039763567974, 'mean_word_length': 3.1422212330291566, 'pattern_counts': {'":': 0, '<': 667, '<?xml version=': 0, '>': 667, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3688064', 'n_tokens_mistral': 6445, 'n_tokens_neox': 6226, 'n_words': 2410}