Skip to content

Introduction To Command Line Tools

Jump to bottom
Tyler Erickson edited this page Feb 11, 2026 · 1 revision

An Introduction to Command Line Tools

This page will go through how to use command line tools for those who are new to them!

While the command line can seem intimidating, openSeaChest tries to keep it simple whenever possible.

This will not be able to capture all aspects of the command line, but we hope this will be a good introduction for you to follow and get more comfortable with it!

Quick Definitions

Some terms you may see are:

  • CLI - Command Line Interface
  • TUI - Text User Interface
  • GUI - Graphical User Interface

openSeaChest tools are CLI tools.

An example of a TUI is older system BIOS that requires changing things with arrow keys, tab, enter key, + or - keys, and the function keys on your keyboard with no option for a mouse.

An example of a GUI is SeaTools, many UEFI configurations have a GUI today, or even using Windows to navigate with a mouse and click virtual buttons to navigate windows that your applications run within.

Permissions

For openSeaChest tools you will need Administrator permissions in Windows or sudo/root permissions in other operating systems like Linux.

The reason for these permissions comes from the OS (Operating System) itself. When openSeaChest accesses your storage device it needs to be able to issue raw commands to the device. The OS may not be able to know and understand the effects of all of these commands, even if they are benign, so the OS requires additional permissions for this interface. This is designed to protect your data from possible deletion or other errors in case a bad actor or someone who is less sure about what they are doing cannot cause data-loss.

While it may seem like it is a risk for you to use openSeaChest if you do not know all the details about these raw commands, Seagate has done its best to provide you the options you want to control your storage and protect your data from mishaps and bad inputs.

Lets Begin!

The first step is to download the openSeaChest tools. Place these in a directory of your choice! It is recommended that they are moved out of the Downloads folder to another location for security so a choice like the Documents folder is a good one.

Next you will need a command window to interact with the CLI.

🪟 Windows Users:

Use Command Prompt (cmd.exe) or PowerShell (both built-in to Windows).

IMPORTANT: Right-click and select "Run as Administrator" - this is required!

💻 Linux/Unix Users (Linux, FreeBSD, macOS, etc.):

Open your terminal application. Common names: Terminal, XTerminal, QTerminal, Konsole

If you cannot find a terminal, search for "terminal" in your system or distribution documentation.

Now you will run your first CLI command: cd in order to change directory to the location of openSeaChest tools.

🪟 Windows:

cd C:\Users\YourUsername\Documents\openSeaChest

(Replace YourUsername with your actual Windows username)

💻 Linux/Unix:

cd ~/Documents/openSeaChest

As you are typing out the directory, you can hit the Tab key in many shells to perform Tab Completion so you do not need to type the full name of a directory manually. Be aware that you must give a starting point, even relative directory, for tab completion to work (ex: ./ or .\). This can be helpful to save time as you get used to the command line, but feel free to try it out! Note that in Windows cmd.exe requires use of \ in the path for tab completion to work correctly.

Note: Bash, cmd.exe, and PowerShell support tab completion. Other shells may or may not have this support.

If you get stuck trying to cd to your directory you can also list the contents of it.

🪟 Windows (cmd.exe):

dir

💻 Linux/Unix & Windows PowerShell:

ls

This will list the contents of your current directory to help you figure out where to navigate to next. You can navigate one or more folders at a time, but if you get stuck just go as far as you can, then list what is in that directory! If you are in Windows, continuing to press tab once in a new directory will cycle through each option in that directory (files and folders). In linux if you keep pressing tab it will list the contents of your directory that match what you have typed so far or if in a fresh directory it will have output similar to ls.

If you are unsure of your current directory, you can use another command to tell you where you are:

🪟 Windows (cmd.exe):

cd

(No arguments - just prints current directory)

💻 Linux/Unix & Windows PowerShell:

pwd

NOTE: Spaces in your path need special handling:

🪟 Windows (cmd.exe) - Use quotes:

cd "C:\Users\Me\Documents\I put my executables here"

🪟 Windows (PowerShell) - Use backtick (`) before each space:

cd C:\Users\Me\Documents\I` put` my` executables` here

💻 Linux/Unix - Use backslash () before each space:

cd ~/Documents/I\ put\ my\ executables\ here

If you have a folder open to openSeaChest you can also try copy-pasting the address from the address bar into the command line after the cd command to save typing as well.

Note: If you have spaces in the name, you may see the system automatically escape them on copy-paste.

⚠️ Command Line Safety Tips

Before we continue, here are some important safety considerations when working with command-line tools:

📁 Avoid Spaces in Folder and File Names

While spaces in paths are supported, they require special escaping (quotes, backslashes, backticks) and can lead to errors if forgotten. For an easier command-line experience:

  • Good: ~/Documents/openSeaChest or C:\Tools\openSeaChest
  • Problematic: ~/Documents/open Sea Chest or C:\My Tools\open Sea Chest

If you are creating new folders for openSeaChest or other CLI tools, use hyphens or underscores instead of spaces.

⚠️ Be Extremely Careful Copy-Pasting Commands

Commands from the internet can be dangerous. Always read and understand a command before running it.

Example of a catastrophic command pattern:

rm -rf <root_directory_path>    # DO NOT RUN - This deletes your entire operating system!

Commands like this recursively remove everything starting from a root directory. Similar dangerous patterns exist on Windows (like del /f /s /q <system_drive>:\*).

Always:

  1. Read the full command before pasting
  2. Understand what each part does
  3. Verify you are in the correct directory
  4. Check that any file paths are what you intend

💾 Critical: Watch for Drive Handles in Examples

Pasting commands with drive handles can cause catastrophic data loss.

Some terminals may execute a pasted command immediately, before you can change the drive handle to the correct one.

Dangerous scenario:

# Example you found online:
sudo ./openSeaChest_Erase -d /dev/sda --sanitize overwrite --poll

# What happens if you paste this:
# 1. You meant to change /dev/sda to /dev/sdb (your USB drive)
# 2. Terminal executes immediately upon paste
# 3. Your primary OS drive (/dev/sda) gets erased instead!

How openSeaChest documentation protects you:

All openSeaChest examples use placeholder handles like:

  • <handle> - Generic placeholder
  • PDX - Windows example (X = placeholder, not a specific drive)
  • /dev/sgX - Linux example (X = placeholder, typically not your OS drive)

This forces you to think about which drive you are targeting.

Other online documentation may not follow this practice. If you see examples with real handles like /dev/sda or PD0, be extremely cautious.

Best practices:

  1. Never paste commands with drive operations directly - type them or paste into a text editor first
  2. Always run -s (scan) first to see your available drives
  3. Verify the handle matches your intended device before running destructive operations
  4. Use --confirm flags when available - gives you a chance to review before execution
  5. Triple-check before running any erase, format, or sanitize command

Remember: There is no "undo" for drive-level operations. Once data is erased or a drive is reformatted, professional data recovery (costing thousands of dollars) may be your only option.

📚 Common Terminal Commands Reference

Here are frequently used terminal commands that will help you work with openSeaChest and manage files:

Navigation and Listing

🪟 Windows (cmd.exe):

cd                          # Show current directory
cd <path>                   # Change directory
dir                         # List files and folders
dir /s                      # List files recursively

🪟 Windows (PowerShell):

pwd                         # Show current directory
cd <path>                   # Change directory
ls                          # List files and folders
ls -Recurse                 # List files recursively
cat <file>                  # Display file contents

💻 Linux/Unix:

pwd                         # Show current directory
cd <path>                   # Change directory
ls                          # List files and folders
ls -la                      # List files with details (including hidden)
cat <file>                  # Display file contents
less <file>                 # View file with scrolling

Redirecting Output to Files

Often you will want to save openSeaChest output to a file for later review or to share with support:

🪟 Windows (cmd.exe & PowerShell):

# Overwrite file (creates new or replaces existing)
.\openSeaChest_Basics.exe -d PDX -i > device_info.txt

# Append to file (adds to end of existing file)
.\openSeaChest_Basics.exe -d PDX --smartAttributes >> all_drives.txt

# Save output AND see it on screen (PowerShell only)
.\openSeaChest_Basics.exe -d PDX -i | Tee-Object -FilePath device_info.txt

💻 Linux/Unix:

# Overwrite file (creates new or replaces existing)
sudo ./openSeaChest_Basics -d /dev/sgX -i > device_info.txt

# Append to file (adds to end of existing file)
sudo ./openSeaChest_Basics -d /dev/sgX --smartAttributes >> all_drives.txt

# Save output AND see it on screen (using tee)
sudo ./openSeaChest_Basics -d /dev/sgX -i | tee device_info.txt

# Append using tee
sudo ./openSeaChest_Basics -d /dev/sgX -i | tee -a device_info.txt

Redirection symbols explained:

  • > - Redirect output to file (overwrites existing file)
  • >> - Redirect output to file (appends to existing file)
  • | - Pipe output to another command
  • tee - Send output to both screen AND file
  • tee -a - Append to file while also showing on screen

Practical examples:

# Save detailed device information
sudo ./openSeaChest_Basics -d /dev/sgX -i --SATInfo > drive_details.txt

# Log scan results from multiple drives
.\openSeaChest_Basics.exe -s >> daily_scan_log.txt

# Monitor a long-running test and save results
sudo ./openSeaChest_GenericTests -d /dev/sgX --longGeneric --poll | tee generic_test.txt

Why this is useful:

  • Save device information before and after firmware updates
  • Keep logs of SMART data for trend analysis
  • Share diagnostic output with support teams
  • Document test results for warranty claims
  • Create records for multiple drives in your system

Running openSeaChest

Now that you have successfully gotten to the directory where the openSeaChest tools are located, lets run them!

💻 Linux/Unix - Set Execute Permissions First:

Before running openSeaChest commands, you need to set execute permissions:

chmod +x ./openSeaChest_*

This sets execute permissions for all openSeaChest tools in the current directory.

Or set permissions for one tool at a time:

chmod +x ./openSeaChest_Basics

🪟 Windows - No Permission Setup Needed:

Windows .exe files are executable by default. Just ensure you opened your terminal as Administrator.

The first thing you will want to do is scan the system to see what devices are detected. You can do this with the -s option.

🪟 Windows:

.\openSeaChest_Basics.exe -s

💻 Linux/Unix:

sudo ./openSeaChest_Basics -s

(Note: sudo is usually required for device access)

NOTE: All openSeaChest tools support the scan option.

This will print out a list of devices that openSeaChest detected in the system with the data separated into columns. Some of the output is informational for you to find your device, but the most important part you will need for all further options is the Handle.

If you do not see any devices or get permission errors:

🪟 Windows Permission Issues:

Symptom: Command window pops up then immediately disappears

Fix: You are not running as Administrator.

  1. Close the current terminal
  2. Right-click Command Prompt or PowerShell
  3. Select "Run as Administrator"
  4. Try the scan command again

💻 Linux/Unix Permission Issues:

Symptom: "Permission denied" or "Access denied" errors

Fix Option 1 - Use sudo (recommended):

sudo ./openSeaChest_Basics -s

Some shells support sudo !! to retry your last command with sudo.

Fix Option 2 - Switch to root user:

sudo su    # Ubuntu/Debian-based systems
su         # Other Unix-like systems

You will need the root password or sudo access.

A Handle is how the operating system identifies your device. openSeaChest needs this to interact with your intended device. Throughout the remaining instructions it will be shown as <handle> which tells you to fill in your actual handle here.

🪟 Windows Handle Format:

Handles look like: PD0, PD1, PD2, etc.

Example: PDX (short for \\\\.\\PhysicalDriveX - openSeaChest accepts both formats)

💻 Linux/Unix Handle Format:

Preferred handles: /dev/sg0, /dev/sg1, /dev/sg2, etc. (we use /dev/sgX in examples)

Also works: /dev/sda, /dev/sdb, /dev/sdc, etc.

Why sg is preferred: sg devices are raw character devices, while sd devices are block devices. Raw character devices provide better passthrough support. openSeaChest will automatically try to map sd to sg if you provide an sd handle.

Now lets run the device information option (-i) to get more information about the drive.

🪟 Windows:

.\openSeaChest_Basics.exe -d PDX -i

(Replace PDX with your actual handle from the scan)

💻 Linux/Unix:

sudo ./openSeaChest_Basics -d /dev/sgX -i

(Replace /dev/sgX with your actual handle from the scan)

This will dump out a lot more information about the device you specified with a handle. You will see capacity, features supported, and much more from this output.

One last important option for you to know about: --help

All of the openSeaChest tools include the option --help or -h for short. This will dump all of the options a given tool supports and some example usage for the tool as well.

At this point you are ready to start digging into the tools in more detail and learning more about your storage device!

Working with Multiple Drives in openSeaChest

If you want to work with more than one drive at a time there are a few options.

You can write a script to interact with each device which gives you much more control over parallelizing options, or you can let openSeaChest interact sequentially with each device.

You can provide a list of devices by using -d <handle> multiple times:

openSeaChest -d /dev/sg443 -d /dev/sg342 -d /dev/sg95 -i

Another option you have is -d all. This will use every handle shown in -s and go through them sequentially performing all other operations you have defined on the command line.

Another option is to specify only specific models with the --modelMatch <modelNumberNoSpaces>:

openSeaChest -d all --modelMatch ST100000NM0001 -i

If you need parallelization, you will need to use a script. (Seagate will put up a page showing examples as soon as we get to writing it to this wiki!)

The openSeaChest Tools

Now that you have the basics to run a CLI tool, you are probably thinking "What tool do I need". Let's go through a brief introduction to each of the tools.

  • openSeaChest_Basics: This tool is more or less a CLI version of SeaTools. It has the common basic options you most likely need for your everyday needs.
  • openSeaChest_Configure: This tool has lots of configuration options to change device behavior. This is the "generic" configuration tool. Some options, such as power options will be found in other tools.
  • openSeaChest_Defect: This tool has options related to the defect management system in a modern storage device. You can view defect lists (if supported by the device) and you can create test defects to test a device's handling of defects.
  • openSeaChest_Erase: This tool contains every method to sanitize your storage with a clear or purge so you can securely remove your data from your drive.
  • openSeaChest_Firmware: This tool is all about upgrading your device firmware to a new revision.
  • openSeaChest_Format: This tool is NOT about erasure, but about changing the formatting of the medium. Changing sector sizes, adding protection information, depopulating a storage element, and more. This affects the medium and the way the drive finds sectors on the medium. Use it with caution!
  • openSeaChest_GenericTests: This tool has some basic testing of a device's Read/Write capabilities.
  • openSeaChest_Info: This tool has option to dump drive information beyond -i. Example: --partitionInfo reads the MBR or GPT partition table for you and displays what it detects on the drive.
  • openSeaChest_NVMe: This tool is for NVMe specific options that do not really fit in with the other tools. While there may be some overlap in other tools, this is intended to handle NVMe unique capabilities. NVMe drives are supported by all openSeaChest tools!
  • openSeaChest_PassthroughTest: This tool is meant to automatically check SATL/SNTL devices (USB, HBAs, Drivers) for known workarounds to get as much support as possible out of them with the openSeaChest tools. You can run the automated test on your device and share it on an openSeaChest issue to improve overall support for your device in future releases.
  • openSeaChest_PowerControl: This tool has options to control all the different features that govern your device's power consumption. Use this to adjust idle and standby timers, configure APM, and more.
  • openSeaChest_Raw: Issue a RAW device command from the command line. Unless you are comfortable with the device standards or vendor unique commands a drive supports, you probably do not want this. If you find yourself using raw commands often for a feature, please request it be added as its own openSeaChest option!
  • openSeaChest_Reservations: This tool handles SCSI/NVMe device reservations. This exposes these commands in easy to use options rather than using a low-level raw command. Unless you are working with special enterprise configurations where multiple systems access a single drive, this will not mean much to you.
  • openSeaChest_Security: This tool holds options related to ATA security and other security features.
  • openSeaChest_SMART: This tool holds the options needed to explore device health and statistics about how it is performing.
  • openSeaChest_ZBD: This tool is all about working with Zoned Block Devices (ZBDs) and offers easy to use options to work with them so a raw command is not necessary. Unless you are working with Host-Managed devices, this tool is probably not something you need.

🚀 Next Steps: Hands-On Tutorials

Now that you understand the basics of using command-line tools, most users will want to start with one of these two essential guides:

Start Here: Most Common Tasks

How To Check Drive Health - Start with this guide!

  • Step-by-step diagnostic workflow from quick SMART checks to thorough testing
  • Learn to interpret drive health indicators and test results
  • Understand when a drive needs attention or replacement
  • Essential for monitoring drive reliability

How To Update Drive Firmware - Critical for drive maintenance

  • Safely update drive firmware with comprehensive safety guidance
  • Understand when and why firmware updates are needed
  • Follow proper procedures to avoid data loss during updates
  • Essential reading before any firmware operation

Additional Common Tasks

Technical Deep Dives

Clone this wiki locally