Storegate CLI (sgcli) User Guide
Storegate CLI (sgcli) User Guide
Introduction
sgcli is a command-line interface (CLI) for managing your Storegate cloud storage directly from the terminal. It
supports fast, resumable file transfers, recursive directory operations, server-side copy/move, and an interactive
dual-pane file manager.
Key Features:
- Cross-Platform: Works on Windows, macOS, and Linux.
- Resumable Transfers: Interrupted uploads and downloads automatically resume from where they left off.
- Recursive Operations: Upload or download entire folder structures with a single command.
- Server-Side Speed: Copy and move files directly on the server — no bandwidth used for the transfer itself.
- Interactive TUI: A full-featured dual-pane terminal file manager (sgcli tui).
- Update Notifications: Automatically notifies you when a newer version is available.
1. Installation
Download the pre-built archive for your operating system from the Releases page.
Archive naming
| Platform | Archive filename |
|----------|-----------------|
| macOS (Apple Silicon M1/M2/M3) | sgcli-darwin-arm64.tar.gz |
| macOS (Intel) | sgcli-darwin-amd64.tar.gz |
| Linux (64-bit) | sgcli-linux-amd64.tar.gz |
| Windows (64-bit) | sgcli-windows-amd64.zip |
Each archive contains a single binary: sgcli (or sgcli.exe on Windows).
macOS
1. Download the .tar.gz archive matching your Mac.
2. Extract it (double-click in Finder, or in Terminal):
tar -xzf sgcli-darwin-arm64.tar.gz
3. Install by moving it to a directory in your PATH:
sudo mv sgcli /usr/local/bin/sgcli
4. Verify:
sgcli --version
Linux
1. Download the .tar.gz archive.
2. Extract:
tar -xzf sgcli-linux-amd64.tar.gz
3. Install:
sudo mv sgcli /usr/local/bin/sgcli
4. Make executable (if needed):
chmod +x /usr/local/bin/sgcli
5. Verify:
sgcli --version
Windows
1. Download the .zip archive.
2. Extract it (right-click → Extract All, or use 7-Zip).
3. Move sgcli.exe to a folder included in your system PATH, for example C:\Tools.
- To add a folder to PATH: System Properties → Advanced → Environment Variables → Path → Edit → New.
4. Verify by opening a new Command Prompt or PowerShell terminal:
sgcli --version
2. Authentication
Logging in
Before using sgcli, log in to your Storegate account. This uses OAuth2 and will open your web browser.
sgcli login
After successful login, sgcli saves an encrypted session file:
| Platform | Location |
|----------|----------|
| macOS / Linux | ~/.storegate_session.bin |
| Windows | %USERPROFILE%\.storegate_session.bin |
The session is automatically refreshed when it expires — you do not need to log in again.
Logging out
sgcli logout
This revokes the session on the server and deletes the local session file.
3. Command Reference
ls — List files and folders
sgcli ls [REMOTE_PATH]
Lists the contents of a remote directory. Defaults to the root (/) if no path is given.
sgcli ls /
sgcli ls /Documents/Reports
put — Upload
sgcli put [LOCAL_PATH] [REMOTE_PATH]
Uploads a local file or folder recursively. If a file already exists at the destination, you will be prompted to
Overwrite, Skip, apply the choice to All remaining conflicts, or Quit.
| Flag | Description |
|------|-------------|
| -f, --force | Overwrite without prompting |
# Upload a single file
sgcli put ./video.mp4 /Videos
# Upload an entire folder recursively
sgcli put ./MyProject /
# Force overwrite
sgcli put config.json /Settings -f
get — Download
sgcli get [REMOTE_PATH] [LOCAL_PATH]
Downloads a remote file or folder recursively. When a partially downloaded file exists locally, you are offered to
Resume, Overwrite, or Skip rather than a generic overwrite prompt.
| Flag | Description |
|------|-------------|
| -f, --force | Overwrite without prompting |
# Download a file to the current directory
sgcli get /Documents/report.pdf .
# Download a folder
sgcli get /Photos ./Downloads -f
cp — Server-side copy
sgcli cp [REMOTE_SOURCE] [REMOTE_DESTINATION]
Copies files or folders directly on the server. No local bandwidth is used.
| Flag | Description |
|------|-------------|
| -f, --force | Overwrite if destination exists |
sgcli cp /Documents/report.pdf /Archive/
sgcli cp /Photos /Backup/Photos_Copy
mv — Move or rename
sgcli mv [REMOTE_SOURCE] [REMOTE_DESTINATION]
Moves or renames a file or folder on the server.
| Flag | Description |
|------|-------------|
| -f, --force | Skip confirmation |
# Rename
sgcli mv /Documents/draft.txt /Documents/final.txt
# Move into a folder
sgcli mv /pic.jpg /Photos/
rm — Delete
sgcli rm [REMOTE_PATH]
Permanently deletes a file or folder.
| Flag | Description |
|------|-------------|
| -f, --force | Delete without confirmation |
sgcli rm /Trash/old_file.txt
sgcli rm /TempFolder -f
mkdir — Create folder
sgcli mkdir [REMOTE_PATH]
Creates a new folder (including intermediate parent folders if they don't exist).
sgcli mkdir /Projects/NewClient/Assets
touch — Create empty file
sgcli touch [REMOTE_PATH]
Creates a new empty file on the server.
| Flag | Description |
|------|-------------|
| -f, --force | Overwrite if file exists |
sgcli touch /Documents/notes.txt
cat — View file content
sgcli cat [REMOTE_FILE_PATH]
Downloads and prints the contents of a remote text file to stdout.
sgcli cat /Settings/config.txt
open — Open in default application
sgcli open [REMOTE_PATH]
Downloads the file to a temporary location and opens it with your system's default application.
Note: This is read-only. Changes will not be saved back to Storegate. To edit and save changes, use F4 in the TUI.
sgcli open /Finance/budget.xlsx
diff — Compare local and remote
sgcli diff [LOCAL_PATH] [REMOTE_PATH]
Compares a local folder with a remote folder and shows differences.
| Status | Meaning |
|--------|---------|
| ✅ OK | Same file exists in both locations (size and date match) |
| 👉 MISSING (Remote) | Exists locally, missing on server |
| 👈 MISSING (Local) | Exists on server, missing locally |
| ⚠️ SIZE | Same name, different file size |
| ⏰ TIME | Same size, different modification time |
| ❌ TYPE | File in one place, folder in the other |
sgcli diff ./Photos /Backup/Photos
df — Storage usage
sgcli df
Shows total capacity, used space, and available space for your account.
du — Disk usage for a path
sgcli du [REMOTE_PATH]
Calculates the total size of a remote file or folder.
sgcli du /Videos
web — Open web interface
sgcli web
Opens your Storegate account in the default web browser.
tui — Terminal User Interface
sgcli tui
Launches the interactive dual-pane file manager (see section 4).
4. Terminal User Interface (TUI)
The TUI provides a dual-pane file manager: the left pane shows your local filesystem, the right pane shows your
Storegate cloud storage.
Keyboard Shortcuts
| Key | Action |
|-----|--------|
| Tab | Switch active pane |
| F1 | Show help |
| F2 | Cycle sort order (Name → Size → Date) |
| F3 | View file content |
| F4 | Edit file (auto-locks on server, uploads on save) |
| Shift+F4 / Ctrl+N | Create new empty file (Touch) |
| F5 | Copy selected items — opens a dialog to edit destination path |
| F6 | Move selected items — opens a dialog to edit destination path |
| Ctrl+E | Rename selected item |
| F7 | Create directory |
| F8 / Del | Delete selected items |
| F9 | Mark files by pattern (e.g. *.txt) |
| F10 | Quit |
| F12 | Toggle pane between Local / Remote view |
| Space | Select / deselect item |
| Ctrl+A | Select all |
| + / - | Select / deselect by pattern |
| * | Invert selection |
| Esc | Abort active transfer (when a transfer is in progress) |
| Ctrl+C | Abort active transfer, or quit if no transfer is running |
Copy and Move dialogs (F5 / F6)
When copying or moving, a dialog opens pre-filled with the destination path. You can:
- Edit the path to move files to a different location.
- Change the filename to rename while copying or moving.
Transfer progress
A progress dialog appears during uploads and downloads, showing the filename, progress bar, and bytes transferred. Press
Esc or Ctrl+C to abort.
5. Shell Autocompletion
Enable tab-completion for commands and remote paths.
Bash
Add to ~/.bashrc or ~/.bash_profile:
source <(sgcli completion bash)
Zsh
Add to ~/.zshrc:
source <(sgcli completion zsh)
Fish
Run once:
sgcli completion fish > ~/.config/fish/completions/sgcli.fish
PowerShell
Add to your profile ($PROFILE):
. (sgcli completion powershell | Out-String)
6. Update Notifications
sgcli automatically checks for new versions after each command. If a newer version is available, a notification is
printed:
💡 New version available!
Download: https://example.com/sgcli-1.1.0-darwin-arm64.tar.gz
The notification is also written to the log file, so it is visible even when output is redirected (e.g. in cron jobs).
The check is silent on all errors (network failures, timeouts, etc.) and never blocks the command from completing.
7. Global Flags
These flags can be used with any command:
| Flag | Description |
|------|-------------|
| --no-log | Disable writing log files to disk |
| --help | Show help for a command |
| --version | Display the current version |
Log files are written to:
| Platform | Location |
|----------|----------|
| macOS | ~/Library/Logs/sgcli/ |
| Linux | ~/.local/state/sgcli/logs/ |
| Windows | %LOCALAPPDATA%\sgcli\Logs\ |