Storegate CLI (sgcli) User Guide
Introduction
Welcome to the sgcli User Guide. This command-line interface (CLI) allows you to interact with your Storegate account
directly from your terminal. It's a powerful tool for managing files, scripting automated tasks, and performing fast,
server-side operations.
Key Features:
- Cross-Platform: Works on Windows, macOS, and Linux.
- Efficient Transfers: Resumable uploads and downloads.
- Recursive Operations: Easily upload or download entire folder structures.
- Server-Side Speed: Copy, move, and rename files directly on the server without using your local bandwidth.
- Interactive & Scriptable: Use it interactively with prompts or automate it in scripts with the --force flag.
1. Installation
You can download the pre-compiled binary for your operating system.
Windows
1. Download the sgcli-windows-amd64.exe file.
2. For ease of use, you can rename it to sgcli.exe.
3. Place the sgcli.exe file in a folder that is included in your system's PATH environment variable (e.g.,
C:\Windows\System32 or a custom folder like C:\Tools). This allows you to run sgcli from any command prompt or
PowerShell terminal.
macOS
1. Download the sgcli-darwin-amd64 (for Intel Macs) or sgcli-darwin-arm64 (for M1/M2/M3 Macs) file.
2. Open your Terminal.
3. Make the file executable:
chmod +x /path/to/downloaded/sgcli-darwin-arm64
4. Move it to a directory in your PATH, like /usr/local/bin, and rename it to sgcli:
sudo mv /path/to/downloaded/sgcli-darwin-arm64 /usr/local/bin/sgcli
You can now run sgcli from any terminal window.
Linux
1. Download the sgcli-linux-amd64 file.
2. Open your terminal.
3. Make the file executable:
chmod +x /path/to/downloaded/sgcli-linux-amd64
4. Move it to a directory in your PATH, like /usr/local/bin:
sudo mv /path/to/downloaded/sgcli-linux-amd64 /usr/local/bin/sgcli
You can now run sgcli from any terminal.
2. Authentication
Logging In
Before you can use the CLI, you must log in to your Storegate account. This process uses OAuth2 and will open your web
browser for authentication.
sgcli login
After you successfully log in, sgcli will store an encrypted session file on your computer (~/.storegate_session.bin on
macOS/Linux and %USERPROFILE%\.storegate_session.bin on Windows). This file allows you to remain logged in between
sessions. The session will automatically refresh when needed.
Logging Out
To log out and delete the local session file, run:
sgcli logout
This will revoke the session on the server and remove your local credentials.
3. Command Reference
ls - List Files and Folders
Lists the contents of a remote directory.
Usage:
sgcli ls [REMOTE_PATH]
If no path is provided, it lists the contents of the root directory.
Examples:
# List contents of the root directory
sgcli ls /
# List contents of a specific folder
sgcli ls /Documents/Reports
put - Upload a File or Folder
Uploads a local file or an entire folder recursively to your Storegate account.
Usage:
sgcli put [LOCAL_PATH] [REMOTE_PATH]
Conflict Handling: If a file with the same name already exists at the destination, you will be prompted to overwrite,
skip, apply the choice to all future conflicts, or quit the operation.
Flags:
- -f, --force: Overwrites any existing files without prompting for confirmation.
Examples:
# Upload a single file to the "Videos" folder
sgcli put ./movie.mp4 /Videos
# Upload an entire local folder "MyProject" to the root directory
sgcli put ./MyProject /
# Upload a file and overwrite it if it exists
sgcli put config.json /Settings -f
get - Download a File or Folder
Downloads a remote file or an entire folder recursively to your local machine.
Usage:
sgcli get [REMOTE_PATH] [LOCAL_PATH]
Conflict Handling: Similar to put, you will be prompted if a file with the same name already exists locally.
Flags:
- -f, --force: Overwrites any existing local files without prompting.
Examples:
# Download a report into the current local directory (.)
sgcli get /Documents/report.pdf .
# Download the entire "Photos" folder into a local "Downloads" directory
sgcli get /Photos ./Downloads
# Download and overwrite any local files
sgcli get /Photos ./Downloads -f
cp - Copy on the Server
Copies a file or folder from one remote location to another. This is a server-side operation and is extremely fast as it
does not use your local internet connection for the transfer.
Usage:
sgcli cp [REMOTE_SOURCE] [REMOTE_DESTINATION]
Flags:
- -f, --force: Overwrites destination files if they exist.
Examples:
# Copy a file to an "Archive" folder
sgcli cp /Documents/report.pdf /Archive/
# Copy an entire folder to a new location
sgcli cp /Photos /Backup/Photos_Copy
mv - Move or Rename
Moves a file or folder to a new remote location, or renames it. This is also a fast, server-side operation.
Usage:
sgcli mv [REMOTE_SOURCE] [REMOTE_DESTINATION]
Flags:
- -f, --force: Perform the move/rename without confirmation.
Examples:
# Rename a file
sgcli mv /Documents/draft.txt /Documents/final_report.txt
# Move a file into another folder
sgcli mv /pic.jpg /Photos/
# Move a folder
sgcli mv /Old_Projects /Archive/Old_Projects
rm - Remove a File or Folder
Permanently deletes a file or folder from your Storegate account.
Usage:
sgcli rm [REMOTE_PATH]
Flags:
- -f, --force: Deletes without asking for confirmation. Use with caution!
Examples:
# Delete a specific file
sgcli rm /Trash/old_file.txt
# Delete an entire folder and its contents without a prompt
sgcli rm /Temporary_Files -f
touch - Create an Empty File
Creates a new, empty file on the remote server. If the file already exists, you will be prompted to overwrite it.
Usage:
sgcli touch [REMOTE_PATH]
Flags:
- -f, --force: Overwrites an existing file without confirmation.
Example:
# Create a new placeholder file
sgcli touch /Documents/new_file.txt
open - Open a Remote File (Read-Only)
Downloads a remote file to a temporary location and opens it using your computer's default application.
⚠️ Important: This command is for viewing only. Any changes you make to the file in your local application will NOT be
saved back to Storegate.
If you need to edit a file and have the changes saved back to the cloud, use the Edit (F4) function within the sgcli
tui.
Usage:
sgcli open [REMOTE_PATH]
Example:
# Open a remote spreadsheet for viewing
sgcli open /Finance/budget.xlsx
mkdir - Create a Folder
Creates a new, empty folder. It can also create nested parent directories if they don't already exist.
Usage:
sgcli mkdir [REMOTE_PATH]
Example:
# Create a new project folder
sgcli mkdir /Projects/New_Client_Project
diff - Compare Local and Remote
Compares a local directory with a remote directory and shows the differences.
Status Meanings:
- ✅ OK: The file exists in both places with the same size and modification time.
- 👉 MISSING (Remote): The file exists locally but not on the server.
- 👈 MISSING (Local): The file exists on the server but not locally.
- ⚠️ SIZE: The file exists in both places but the sizes differ.
- ⏰ TIME: The file sizes are the same, but modification times differ.
- ❌ TYPE: The item is a file in one place and a folder in the other.
Usage:
sgcli diff [LOCAL_PATH] [REMOTE_PATH]
Example:
# Compare local "Photos" with remote "Backup/Photos"
sgcli diff ./Photos /Backup/Photos
df - Show Storage Usage
Displays the total storage capacity, used space, and available space for your Storegate account.
Usage:
sgcli df
du - Show Disk Usage
Calculates and displays the total size of a specific remote file or folder.
Usage:
sgcli du [REMOTE_PATH]
Example:
# Get the size of the "Videos" folder
sgcli du /Videos
cat - View File Content
Downloads and prints the content of a remote file directly to the terminal.
Usage:
sgcli cat [REMOTE_FILE_PATH]
Example:
# View the contents of a configuration file
sgcli cat /Settings/config.txt
web - Open in Browser
Opens your Storegate account in your default web browser.
Usage:
sgcli web
tui - Terminal User Interface
Launches the interactive dual-pane file manager.
Usage:
sgcli tui
(Or simply run sgcli if configured)
Keyboard Shortcuts:
- Tab: Switch between Left (Local) and Right (Remote) panes.
- F1: Show Help.
- F2: Cycle Sort (Name -> Size -> Date).
- F3: View file content (internal viewer for text, external app for others).
- F4: Edit file. Opens in default local editor. Automatically locks file on server and uploads on save.
- F5: Copy selected items. Opens a dialog to edit the destination path (supports "Copy As").
- F6: Move selected items. Opens a dialog to edit the destination path (supports "Move As"/Rename).
- Ctrl+E: Quick rename of the selected item in place.
- F7: Make Directory.
- F8 / Del: Delete selected items.
- F9: Mark files by pattern (glob, e.g. *.txt).
- F10: Exit.
- Ctrl+C: Cancel ongoing transfer or exit program.
- Ctrl+N: Create a new empty file (Touch).
- F12: Toggle active pane between Local/Remote view.
- Space: Select/Deselect file.
- Ctrl+A: Select all.
- +/-: Mark by pattern (e.g. *.txt).
- *****: Invert selection.
4. Shell Autocompletion
sgcli can generate autocompletion scripts for various shells, which is highly recommended for a better user experience.
It enables you to complete commands and remote file paths by pressing the Tab key.
Generating the Script
First, run the completion command followed by the name of your shell.
- Bash: sgcli completion bash
- Zsh: sgcli completion zsh
- Fish: sgcli completion fish
- PowerShell: sgcli completion powershell
Permanent Installation
Bash (Linux/macOS)
Add the following line to your ~/.bash_profile or ~/.bashrc:
source <(sgcli completion bash)
Reload your shell with source ~/.bash_profile or open a new terminal.
Zsh (macOS/Linux)
Add the following line to your ~/.zshrc:
source <(sgcli completion zsh)
Reload your shell with source ~/.zshrc or open a new terminal.
Fish (Linux/macOS)
Run this command once in your terminal:
sgcli completion fish > ~/.config/fish/completions/sgcli.fish
This will create the completion file in the correct directory.
PowerShell (Windows)
1. Open your PowerShell profile script for editing:
notepad $PROFILE
2. Add the following line to the file and save it:
. (sgcli completion powershell | Out-String)
3. Reload your profile or open a new PowerShell terminal.
5. Global Flags
These flags can be used with any command.
- --no-log: Disables writing log files to disk. (Logs are normally stored in a system-specific log directory).
- --help: Shows help for sgcli or a specific command.
- --version: Displays the current version of sgcli.