STACIO WIKI · User Guide

Stacio Files Guide

1. Files capability overview

The Stacio Files workspace places local directories, remote directories, and the transfer queue in one window. According to the session protocol, it uses built-in SSH/SCP, SFTP, or FTP runtimes and does not depend on the system scp, sftp, or rsync command.

The File Sync advanced entitlement primarily controls batch Remote Edit entry points such as Sync Changed Edited Files. Ordinary browsing and transfers still depend on protocol, connection state, and remote permission.

Files does not parse a separate new remote address. It inherits the connection endpoint of an SSH terminal or an SFTP, FTP, or SCP session. When you create a file-protocol session directly, use an IP in most cases or a hostname where appropriate:

Do not enter the complete 192.168.1.20:2222 into a saved session's Host field. A remote path field accepts only a path such as ~ or /srv/app, never an IP, hostname, or URL.

2. Open Files

2.1 Open from an SSH terminal

1. Open and select an SSH tab that is connected successfully.
2. Choose View > Files or click the Files toolbar control.
3. Files binds to the current terminal and starts loading the remote home directory ~.
4. When directory follow is enabled, Files attempts to enter the same directory after a successful terminal cd.

If Stacio says no SSH file context is available, confirm that the selected tab is an active SSH terminal rather than Local Shell, Telnet, VNC, Browser, a split container, or a disconnected tab.

2.2 Open a file-protocol session directly

Opening an SFTP, FTP, or SCP session from the left session list enters the file workspace directly. Connection still uses the respective authentication flow; SSH-family protocols also validate host keys.

2.3 Files and terminal binding

• Files runs operations only against the currently bound remote runtime.
• When switching terminals, check that the IP/hostname, port, account, and top path all belong to the intended target.
• Closing or reconnecting the terminal can stop active work, and Files shows a disconnected state.
• Unsaved Remote Edit content asks for confirmation before closing; do not rely on a disconnect to save it automatically.

3. Know the file workspace

3.1 Local and remote columns

An independent file workspace normally includes:

• Local Files on the left for a directory on the current Mac;
• Files on the right for the current session's remote directory;
• an expandable editor or media preview on the right;
• a Transfers queue in the inspector.

You can drag a divider to adjust width. The UI saves some workspace widths but does not alter file contents.

3.2 Remote toolbar

Common controls include:

• go to parent directory;
• path field;
• refresh remote directory;
• search;
• show or hide dotfiles;
• upload a file or folder;
• download selected items;
• more-actions menu.

Lists can show name, type, size, modification time, owner, and permissions. Exact fields depend on protocol and server response.

4. Browse and locate

4.1 Path rules

• ~ means the remote account's home directory;
• / means the remote filesystem root;
• enter an absolute path or a ~/... path in the path field;
• double-click a directory to enter it and use Up to return to its parent;
• when a path lacks permission, is deleted, or contains unsafe content, Stacio cancels the operation and reports an error.

Do not infer write permission from a visible path. Read, create, rename, delete, and chmod can each be limited by different remote permissions.

4.2 Hidden files

The hidden-files toolbar control temporarily shows or hides items beginning with .. The default for a new Files panel is controlled by Stacio > Settings > Files > Show Hidden Files by Default.

When showing .env, .ssh, .config, or similar files, avoid exposing sensitive content through screenshots, AI context, or screen sharing.

4.3 Remote search

1. Click Search.
2. Enter a filename keyword.
3. Set search depth from 1 to 20; the default is 5.
4. Open a result or reveal its directory.
5. Close the search bar to return to the ordinary directory list.

Search starts at the current directory. Greater depth visits more directories and can increase server load and wait time. On production hosts, start shallow and avoid broad searches from /. FTP does not currently provide this remote-search entry point.

4.4 Terminal interaction

The context menu for a remote item can provide:

• Copy File Path;
• Copy File Path to Terminal;
• Copy File Name to Terminal;
• middle-click to send the file name to the currently bound terminal.

Sending to a terminal only writes text. It does not guarantee safe shell escaping or execute a command. Check quoting before submitting paths containing spaces, quotes, or shell metacharacters.

5. Upload and download

5.1 Upload files

1. Enter the destination directory in the remote column.
2. Open Upload and choose Upload File or Upload Folder.
3. Select local items.
4. Resolve an existing target using the conflict policy.
5. Confirm job state and final bytes in the Transfers panel.

You can also drag files from Finder or the local-file column onto a remote directory. Dropping on a remote directory row uses that row as destination; dropping on empty list space uses the current directory.

5.2 Download files

1. Select one or more remote files or directories.
2. Click Download or choose Download from the context menu.
3. Choose a save location for one file, or a destination folder for multiple items.
4. Verify the result in the local-file column or Finder.

Remote items can also be dragged directly to a local directory. A completion notification does not prove content is correct; for important files, verify size, hash, or parseability.

5.3 Transfer conflicts

When a target path already exists, choose one of these policies:

Set the default in Stacio > Settings > Files > Transfer Conflict Policy. Always overwriting reduces prompts and increases the impact of mistakes; production use should normally keep Ask Every Time.

6. Transfer queue

View > Transfers shows upload and download jobs with direction, file, progress, state, and diagnostics. Available controls depend on state:

• Pause: interrupt the job while keeping resumable information;
• Resume: return a paused job to the queue;
• Stop: stop the job while preserving a restart option;
• Retry: run a failed job again;
• Restart: run a paused or retryable job from the beginning;
• Clear Finished: remove completed, failed, or cancelled entries from the queue view.

When network or server does not support resume, Resume can still resend some or all content. Closing a session or the app stops jobs that depend on that runtime. Never treat queued or running as proof that a remote host received a complete file.

Completion requires at least:

1. the job is marked complete;
2. transferred bytes equal expected bytes;
3. target file exists and its size is reasonable;
4. configuration, archive, or data files receive targeted validation.

7. Remote file operations

7.1 Create, rename, and delete

Use More or a context menu to:

• Create Remote Directory;
• Create Remote File;
• Rename Remote Item;
• Delete Remote Item.

Rename input is the new remote path. Delete asks for confirmation, but remote deletion normally does not enter the macOS Trash and may not be recoverable. Confirm directory contents and host before deletion.

7.2 Properties and permissions

Choose Properties or Permissions from a context menu to view remote metadata. SSH, SCP, and SFTP sessions can use Change Remote Permissions and enter an octal chmod value, for example:

644
755
600

Understand file and directory read, write, and execute semantics before entering a value. Never use 777 merely to resolve a permission problem; first identify owner, group, service account, and minimum needed permission. FTP currently does not provide chmod.

8. Remote Edit

8.1 Edit in Stacio

1. Select an editable text file.
2. Choose Open in Stacio Editor from its context menu, or Edit Local Copy from More.
3. Stacio downloads remote content to its managed cache and opens it in the built-in editor.
4. Save changes and watch Saving, Saved, or Save Failed state.
5. Read the remote file again or use a targeted application check to confirm the change took effect.

The editor supports multiple document tabs. Unsaved documents show a status marker, and closing the editor or workspace prompts to save, discard, or cancel closing.

8.2 Use an external app

From a context menu, choose:

• Open With...;
• Open with Default App...;
• open the local copy with the default text editor.

An external app edits local cache only. When Settings > Files > Detect Local Edit Copy Changes is enabled, Files detects a change and offers to synchronize it through the transfer queue; it never overwrites a remote file silently.

8.3 Save and remote conflict

On save, Stacio attempts to check the remote modification time. If another person or process changed the remote file after it was opened, Stacio blocks a direct overwrite and reports that the remote file changed.

When this happens:

1. retain the current local copy;
2. download the latest remote version again;
3. compare differences;
4. merge manually;
5. save a backup copy, then upload.

Do not click Save repeatedly to bypass a remote-change warning.

8.4 Sync changed edited files

Sync Changed Edited Files in More scans Remote Edit cache for the current session and queues detected local changes for upload. This entry point is controlled by the File Sync License.

Before batch sync, verify every file, host, and environment. Entry-point completion only means jobs entered the queue; inspect every upload result in Transfers.

9. Preview, open, and compare

• Previewable media can be opened with Preview in Stacio.
• Other files can be downloaded locally and opened with the default or a chosen app.
• Select two remote files to use Compare Files....
• Comparison downloads two local copies, then invokes FileMerge. Stacio reports unavailable when Xcode is not installed or FileMerge is not found.
• FTP currently does not provide two-file comparison.

Opening or previewing a large file creates local cache and transfer delay. Do not pass customer data or key material to a local application without authorization.

10. Backup and restore

10.1 Back up edited files

When the built-in editor is open, the inspector header shows Back Up Current Edited Files:

1. Click the backup control.

2. Select one or more currently open files.

3. Choose remote same-directory backup or local download.

4. Stacio creates a copy with this name:

   original-file-name-yyyyMMddHHmm.bak

5. Verify that the backup exists, has a reasonable size, and can be read.

Remote backup copies the current remote file; local backup downloads through the transfer queue. Seeing a backup job is not proof that the backup can be restored.

10.2 Restore a backup

Use Restore Backup File in the inspector header and choose either:

• a .bak file with the naming convention in the current remote directory;
• a local backup file with the naming convention.

Restore removes the timestamp and .bak suffix and writes back to the original name. If the target already exists, follow the conflict policy and change workflow. After restore, read the file again and run syntax, service-health, or business validation.

11. Files settings and cache

Stacio > Settings > Files can configure:

Before clearing cache, check the count of unsaved remote edits. Cache cleanup does not delete real download folders, session database, or credentials, but it makes unsynchronized local edit copies unrecoverable.

12. Security and change guidance

• First confirm IP/hostname, port, account, protocol, remote path, and environment.
• Use FTP only on trusted networks and migrate to SFTP where possible.
• Do not expose passwords, tokens, or private keys in file names, macros, logs, or screenshots.
• Before production configuration changes, create a verified backup and prepare rollback commands.
• Treat delete, overwrite, chmod, restore, and batch sync as change operations.
• Validate a completed transfer using a hash, parser, configuration test, or application health check.
• Remove sensitive local copies and diagnostic material that are no longer needed when work ends.

See Security and Governance for broader controls and Remote Operations for change validation.

13. Common questions

When reporting a problem, include Stacio version, protocol, direction of operation, redacted source and destination paths, job time, queue state, and error information. Do not attach credentials or sensitive file contents.