ffsend/README.md

754 lines
28 KiB
Markdown
Raw Normal View History

2019-03-01 11:28:33 +00:00
[![Build status on GitLab CI][gitlab-ci-master-badge]][gitlab-ci-link]
[![Newest release on crates.io][crate-version-badge]][crate-link]
[![Number of downloads on crates.io][crate-download-badge]][crate-link]
[![Project license][crate-license-badge]](LICENSE)
[crate-download-badge]: https://img.shields.io/crates/d/ffsend.svg
[crate-license-badge]: https://img.shields.io/crates/l/ffsend.svg
2019-03-01 11:28:33 +00:00
[crate-link]: https://crates.io/crates/ffsend
[crate-version-badge]: https://img.shields.io/crates/v/ffsend.svg
[gitlab-ci-link]: https://gitlab.com/timvisee/ffsend/pipelines
[gitlab-ci-master-badge]: https://gitlab.com/timvisee/ffsend/badges/master/pipeline.svg
# ffsend [WIP]
2018-05-19 17:33:06 +00:00
> Easily and securely share files from the command line.
2018-05-17 22:08:05 +00:00
> A fully featured [Firefox Send][send] client.
2018-05-19 17:33:06 +00:00
Easily and securely share files and directories from the command line through a
safe, private and encrypted link using a single simple command.
Files are shared using the [Send][send] service and may be up
2018-05-17 22:30:26 +00:00
to 2GB. Others are able to download these files with this tool, or through
2019-01-03 12:16:24 +00:00
their web browser.
2018-05-17 22:30:26 +00:00
2018-06-04 23:06:12 +00:00
[![ffsend usage demo][usage-demo-svg]][usage-demo-asciinema]
_No demo visible here? View it on [asciinema][usage-demo-asciinema]._
2018-05-17 22:30:26 +00:00
All files are always encrypted on the client, and secrets are never shared with
the remote host. An optional password may be specified, and a default file
lifetime of 1 (up to 20) download or 24 hours is enforced to ensure your stuff
does not remain online forever.
This provides a secure platform to share your files.
Find out more about security [here](#security).
2018-05-17 22:08:05 +00:00
- [Features](#features)
- [Usage](#usage)
- [Requirements](#requirements)
- [Install](#install) ([Linux](#linux-all-distributions), [macOS](#macos), [Windows](#windows), [_Other OS/arch_](#other-os-or-architecture))
2018-05-17 22:08:05 +00:00
- [Build](#build)
- [Configuration and environment](#configuration-and-environment)
2018-05-19 17:33:06 +00:00
- [Security](#security)
2018-05-17 22:08:05 +00:00
- [Help](#help)
2018-06-01 14:14:42 +00:00
- [Special thanks](#special-thanks)
2018-05-17 22:08:05 +00:00
- [License](#license)
2018-05-17 22:30:26 +00:00
The public [Send][send] service that is used as default host is provided by
[Mozilla][mozilla].
This application is not affiliated with [Mozilla][mozilla], [Firefox][firefox]
or [Firefox Send][send] in any way.
2018-05-17 22:30:26 +00:00
_Note: this tool is currently in alpha_
2018-05-17 22:30:26 +00:00
2018-05-17 22:08:05 +00:00
## Features
- Fully featured and friendly command line tool
- Upload and download files and directories securely
2018-05-17 22:30:26 +00:00
- Always encrypted on the client
2018-08-02 00:57:43 +00:00
- Additional password protection, generation and configurable download limits
- File and directory archiving and extraction
2019-03-15 00:16:41 +00:00
- Built-in share URL shortener and QR code generator
- Supports old and new Firefox Send server versions
2018-05-17 22:08:05 +00:00
- History tracking your files for easy management
- Ability to use custom Send hosts
2018-05-17 22:30:26 +00:00
- Inspect or delete shared files
- Accurate error reporting
- Streaming encryption and uploading/downloading, very low memory footprint
2019-03-19 23:20:06 +00:00
- Intended for use in [scripts](#scriptability) without interaction
2019-03-13 13:54:43 +00:00
- Upcoming: Firefox Account integration (higher download counts, longer expiry times)
2018-05-17 22:08:05 +00:00
2018-05-18 12:45:00 +00:00
For a list of upcoming features and ideas, take a look at the
current [open issues](https://gitlab.com/timvisee/ffsend/issues) over on GitLab.
2018-05-18 12:45:00 +00:00
2018-05-17 22:08:05 +00:00
## Usage
2018-05-17 22:30:26 +00:00
Easily upload and download:
2018-05-17 22:08:05 +00:00
```bash
# Simple upload
$ ffsend upload my-file.txt
Share link: https://send.firefox.com/#sample-share-url
2018-05-17 22:08:05 +00:00
# Advanced upload
# - Specify a download limit of 20
# - Enter a password to encrypt the file
# - Archive the file before uploading
# - Copy the shareable link to your clipboard
# - Open the shareable link in your browser
$ ffsend upload --downloads 20 --password --archive --copy --open my-file.txt
Password: ******
Share link: https://send.firefox.com/#sample-share-url
2018-05-17 22:08:05 +00:00
2018-05-17 22:30:26 +00:00
# Upload to your own host
$ ffsend u -h https://example.com/ my-file.txt
Share link: https://example.com/#sample-share-url
2018-05-17 22:30:26 +00:00
2018-05-17 22:08:05 +00:00
# Simple download
$ ffsend download https://send.firefox.com/#sample-share-url
2018-05-17 22:30:26 +00:00
```
Inspect remote files:
```bash
# Check if a file exists
$ ffsend exists https://send.firefox.com/#sample-share-url
Exists: yes
# Fetch remote file info
$ ffsend info https://send.firefox.com/#sample-share-url
ID: b087066715
Name: my-file.txt
Size: 12 KiB
MIME: text/plain
Downloads: 0 of 10
Expiry: 18h2m (64928s)
2018-05-17 22:30:26 +00:00
```
Other commands include:
2019-03-25 16:40:53 +00:00
2018-05-17 22:30:26 +00:00
```bash
# View your file history
$ ffsend history
2018-05-18 12:45:00 +00:00
# LINK EXPIRY OWNER TOKEN
1 https://send.firefox.com/#sample-share-url 23h57m eea9f544f6d5df8a5afd
2 https://send.firefox.com/#other-sample-url 17h38m 1e9fef63fee3baaf54ce
3 https://example.com/#sample-share-url 37m30s 8eb28bc1bc85cfdab0e4
2018-05-17 22:30:26 +00:00
# Change the password after uploading
$ ffsend password https://send.firefox.com/#sample-share-url
Password: ******
2018-05-17 22:30:26 +00:00
# Delete a file
$ ffsend delete https://send.firefox.com/#sample-share-url
2018-05-17 22:08:05 +00:00
```
2018-05-18 12:45:00 +00:00
Use the `--help` flag, `help` subcommand, or see the [help](#help) section for
all available subcommands.
2018-05-17 22:08:05 +00:00
## Requirements
- Linux, Windows or macOS
- A terminal :sunglasses:
- Internet connection for uploading and downloading
2018-05-18 08:03:19 +00:00
- Linux specific:
- OpenSSL & CA certificates:
- Ubuntu, Debian and derivatives: `apt install openssl ca-certificates`
- Optional: `xclip` for clipboard support
- Ubuntu, Debian and derivatives: `apt install xclip`
2018-05-18 08:03:19 +00:00
- CentOS/Red Hat/openSUSE/Fedora: `yum install xclip`
- Arch: `pacman -S xclip`
- Windows specific:
- OpenSSL v1.1.0j: [» Installer][openssl-windows-installer]
- macOS specific:
- OpenSSL: `brew install openssl@1.1`
2018-05-17 22:08:05 +00:00
## Install
2018-05-31 20:33:09 +00:00
Because `ffsend` is still in alpha, only limited installation options are
available right now.
2018-05-31 20:33:09 +00:00
Make sure you meet and install the [requirements](#requirements).
See the operating system specific instructions below:
* [Linux](#linux-all-distributions)
* [macOS](#macos)
* [Windows](#windows)
* [_Other OS or architecture_](#other-os-or-architecture)
### Linux (all distributions)
Using the [snap](#linux-snap-package) package is recommended if supported.
Alternatively you may install it manually using the
[prebuilt binaries](#linux-prebuilt-binaries).
Only 64-bit (`x86_64`) packages and binaries are provided.
For other architectures and configurations you may [compile from source](#build).
More packages options will be coming soon.
#### Linux: snap package
_Note: The `ffsend` `snap` package is isolated, and can only access files in
your home directory. Choose a different installation option if you don't want
this limitation._
`ffsend`][snapcraft-ffsend]
```bash
snap install ffsend
ffsend --help
```
#### Linux: Arch AUR packages
`ffsend`][aur-ffsend] (binary package)
`ffsend-git`][aur-ffsend-git] (compile from source package)
2019-01-12 22:19:11 +00:00
```bash
yaourt -S ffsend
# or
yay ffsend
2019-03-04 15:33:46 +00:00
# or
aurget -S ffsend
2019-01-12 22:19:11 +00:00
# or using any other AUR installer
ffsend --help
```
#### Linux: Nix package
_Note: The Nix package is currently not automatically updated, therefore it
2019-03-25 16:40:53 +00:00
might be slightly outdated. Open an issue if you believe an important update
is missing._
```bash
nix-channel --update
nix-env --install ffsend
ffsend --help
2019-01-12 22:19:11 +00:00
```
2019-03-25 19:12:35 +00:00
#### Linux: Fedora package
_Note: The Fedora package is maintained by contributors, it might be outdated.
Choose a different installation method if an important update is missing._
2019-03-25 19:12:35 +00:00
```bash
yum install ffsend
ffsend --help
```
#### Linux: Prebuilt binaries
Check out the [latest release][github-latest-release] assets for Linux binaries.
Use the `ffsend-v*-linux-x64-static` binary, to minimize the chance for issues.
If it isn't available yet, you may use an artifact from a
[previous version][github-releases] instead, until it is available.
Make sure you meet and install the [requirements](#requirements) before you
continue.
You must make the binary executable, and may want to move it into `/usr/bin` to
make it easily executable:
```bash
# Rename binary to ffsend
mv ./ffsend-* ./ffsend
# Mark binary as executable
chmod a+x ./ffsend
# Move binary into path, to make it easily usable
sudo mv ./ffsend /usr/local/bin/
ffsend --help
```
### macOS
Using the [`homebrew` package](#macos-homebrew-package) is recommended.
Alternatively you may install it manually using the
[prebuilt binaries](#macos-prebuilt-binaries).
#### macOS: homebrew package
Make sure you've [`homebrew`][homebrew] installed, and run:
```bash
brew install ffsend
ffsend --help
```
#### macOS: Nix package
_Note: The Nix package is currently not automatically updated, therefore it
might be slightly outdated. Open an issue if you believe an important update
is missing._
```bash
nix-channel --update
nix-env --install ffsend
ffsend --help
```
#### macOS: Prebuilt binaries
Check out the [latest release][github-latest-release] assets for a macOS binary.
If it isn't available yet, you may use an artifact from a
[previous version][github-releases] instead, until it is available.
You must install `openssl` through [`homebrew`][homebrew] which `ffsend` depends
on.
2019-03-13 13:56:24 +00:00
Then, mark the downloaded binary as an executable.
You then may want to move it into `/usr/local/bin/` to make the `ffsend` command
globally available:
```bash
# Install openssl dependency
brew install openssl@1.1
# Rename file to ffsend
mv ./ffsend-* ./ffsend
# Mark binary as executable
chmod a+x ./ffsend
# Move binary into path, to make it easily usable
sudo mv ./ffsend /usr/local/bin/
ffsend
```
### Windows
2019-03-14 09:11:58 +00:00
Using the [`scoop` package](#windows-scoop-package) is recommended.
Alternatively you may install it manually using the
[prebuilt binaries](#windows-prebuilt-binaries).
If you're using the [Windows Subsystem for Linux][wsl], it's highly recommended
to install the [prebuilt Linux binary](#prebuilt-binaries-for-linux) instead.
Only 64-bit (`x86_64`) binaries are provided.
For other architectures and configurations you may [compile from source](#build).
A `chocolatey` package along with an `.msi` installer will be coming soon.
2019-03-14 09:11:58 +00:00
#### Windows: scoop package
2019-03-15 00:16:41 +00:00
Make sure you've [`scoop`][scoop-install] installed, and run:
2019-03-14 09:11:58 +00:00
```bash
scoop install ffsend
ffsend --help
```
#### Windows: Prebuilt binaries
Check out the [latest release][github-latest-release] assets for Windows binaries.
Use the `ffsend-v*-windows-x64-static` binary, to minimize the chance for issues.
If it isn't available yet, you may use an artifact from a
[previous version][github-releases] instead, until it is available.
You must install OpenSSL 1.1.0j which `ffsend` depends on. The installer for
this can be found here: [» Installer][openssl-windows-installer]
You can use `ffsend` from the command line in the same directory:
```cmd
.\ffsend.exe --help
```
To make it globally invokable as `ffsend`, you must make the binary available in
your systems `PATH`. The easiest solution is to move it into `System32`:
```cmd
move .\ffsend.exe C:\Windows\System32\ffsend.exe
```
### Other OS or architecture
2019-03-13 17:56:04 +00:00
If your system runs Docker, you can use the [docker image](#docker-image).
There are currently no other binaries or packages available.
You can [build the project from source](#build) instead.
2018-05-17 22:08:05 +00:00
2019-03-13 17:56:04 +00:00
#### Docker image
A Docker image is available for using `ffsend` running in a container.
Mount a directory to `/data`, so it's accessible for `ffsend` in the container,
and use the command as you normally would.
`timvisee/ffsend`][docker-hub-ffsend]
```bash
# Invoke without arguments
docker run --rm -it -v $(pwd):/data timvisee/ffsend
# Upload my-file.txt
docker run --rm -it -v $(pwd):/data timvisee/ffsend upload my-file.txt
# Download from specified link
docker run --rm -it -v $(pwd):/data timvisee/ffsend download https://send.firefox.com/#sample-share-url
# Show help
docker run --rm -it -v $(pwd):/data timvisee/ffsend help
2019-03-25 16:40:53 +00:00
# To update the used image
docker pull timvisee/ffsend
2019-03-18 20:29:12 +00:00
```
2019-03-18 16:09:03 +00:00
2019-03-18 20:29:12 +00:00
On Linux or macOS you might define a alias in your shell configuration, to make
it invokable as `ffsend`:
2019-03-25 16:40:53 +00:00
2019-03-18 20:29:12 +00:00
```bash
2019-03-18 16:09:03 +00:00
alias ffsend='docker run --rm -it -v "$(pwd):/data" timvisee/ffsend'
2019-03-13 17:56:04 +00:00
```
_Note: This implementation is limited to accessing the paths you make available
through the specified mount._
2019-03-18 20:29:12 +00:00
2018-05-17 22:08:05 +00:00
## Build
2018-05-17 22:30:26 +00:00
To build and install `ffsend` yourself, you meet the following requirements
before proceeding:
2018-05-17 22:08:05 +00:00
### Build requirements
2018-05-17 22:30:26 +00:00
- Regular [requirements](#requirements)
- [`git`][git]
2019-03-03 15:52:17 +00:00
- [`rust`][rust] `v1.32` or higher (install using [`rustup`][rustup])
2018-05-17 22:30:26 +00:00
- [OpenSSL][openssl] or [LibreSSL][libressl] libraries and headers must be available
2018-05-17 22:08:05 +00:00
- Linux:
- Ubuntu, Debian and derivatives: `apt install build-essential cmake pkg-config libssl-dev`
- CentOS/Red Hat/openSUSE: `yum install gcc gcc-c++ make cmake openssl-devel`
- Arch: `pacman -S openssl base-devel`
- Gentoo: `emerge -a dev-util/pkgconfig dev-util/cmake dev-libs/openssl`
- Fedora: `dnf install gcc gcc-c++ make cmake openssl-devel`
- Or see instructions [here](https://github.com/sfackler/rust-openssl#linux)
- Windows:
- See instructions here [here](https://github.com/sfackler/rust-openssl#windows-msvc)
2018-05-17 22:08:05 +00:00
- macOS:
- Using `brew`: `brew install cmake pkg-config openssl`
2018-05-17 22:08:05 +00:00
- Or see instructions [here](https://github.com/sfackler/rust-openssl#osx)
### Compile and install
2018-05-17 22:30:26 +00:00
Then, walk through one of the following steps to compile and install `ffsend`:
2018-05-17 22:08:05 +00:00
- Compile and install it directly from cargo:
```bash
# Compile and install from cargo
cargo install ffsend -f
# Start using ffsend
ffsend --help
```
- Or clone the repository and install it with `cargo`:
2018-05-17 22:08:05 +00:00
```bash
# Clone the project
git clone https://github.com/timvisee/ffsend.git
cd ffsend
2018-05-17 22:08:05 +00:00
# Compile and install
2019-03-18 20:29:12 +00:00
cargo install --path . -f
2018-05-17 22:08:05 +00:00
# Start using ffsend
ffsend --help
# or run it directly from cargo
cargo run --release -- --help
```
- Or clone the repository and invoke the binary directly (Linux/macOS):
```bash
# Clone the project
git clone https://github.com/timvisee/ffsend.git
cd ffsend
# Build the project (release version)
cargo build --release
# Start using ffsend
./target/release/ffsend --help
```
### Compile features / use flags
2018-05-18 08:03:19 +00:00
Different use flags are available for `ffsend` to toggle whether to include
various features.
The following features are available, some of which are enabled by default:
| Feature | Enabled | Description |
| :------------: | :-----: | :--------------------------------------------------------- |
| `send2` | Default | Support for Firefox Send v2 servers |
| `send3` | Default | Support for Firefox Send v3 servers |
| `clipboard` | Default | Support for copying links to the clipboard |
| `history` | Default | Support for tracking files in history |
| `archive` | Default | Support for archiving and extracting uploads and downloads |
| `qrcode` | Default | Support for rendering a QR code for a share URL |
| `urlshorten` | Default | Support for shortening share URLs |
| `infer-command`| Default | Support for inferring subcommand based on binary name |
| `no-color` | | Compile without color support in error and help messages |
2018-05-18 08:03:19 +00:00
To enable features during building or installation, specify them with
`--features <features...>` when using `cargo`.
You may want to disable default features first using
2018-05-18 08:03:19 +00:00
`--no-default-features`.
Here are some examples:
```bash
2018-05-18 08:03:19 +00:00
# Defaults set of features with no-color, one of
cargo install --features no-color
cargo build --release --features no-color
2018-05-18 08:03:19 +00:00
# None of the features
cargo install --no-default-features
# Only history and clipboard support
cargo install --no-default--features --features history,clipboard
```
For Windows systems it is recommended to provide the `no-color` flag, as color
support in Windows terminals is flaky.
## Configuration and environment
The following environment variables may be used to configure the following
2018-05-18 12:45:00 +00:00
defaults. The CLI flag is shown along with it, to better describe the relation
to command line arguments:
| Variable | CLI flag | Description |
| :------------------------ | :----------------------------: | :-------------------------------------------- |
| `FFSEND_HISTORY` | `--history <FILE>` | History file path |
| `FFSEND_HOST` | `--host <URL>` | Upload host |
| `FFSEND_TIMEOUT` | `--timeout <SECONDS>` | Request timeout (0 to disable) |
| `FFSEND_TRANSFER_TIMEOUT` | `--transfer-timeout <SECONDS>` | Transfer timeout (0 to disable) |
| `FFSEND_API` | `--api <VERSION>` | Server API version, `-` to lookup |
| `FFSEND_BASIC_AUTH` | `--basic-auth <USER:PASSWORD>` | Basic HTTP authentication credentials to use. |
These environment variables may be used to toggle a flag, simply by making them
available. The actual value of these variables is ignored, and variables may be
empty.
| Variable | CLI flag | Description |
| :------------------- | :-------------: | :--------------------------------- |
| `FFSEND_FORCE` | `--force` | Force operations |
| `FFSEND_NO_INTERACT` | `--no-interact` | No interaction for prompts |
| `FFSEND_YES` | `--yes` | Assume yes for prompts |
| `FFSEND_INCOGNITO` | `--incognito` | Incognito mode, don't use history |
| `FFSEND_OPEN` | `--open` | Open share link of uploaded file |
| `FFSEND_ARCHIVE` | `--archive` | Archive files uploaded |
| `FFSEND_EXTRACT` | `--extract` | Extract files downloaded |
| `FFSEND_COPY` | `--copy` | Copy share link to clipboard |
| `FFSEND_COPY_CMD` | `--copy-cmd` | Copy download command to clipboard |
| `FFSEND_QUIET` | `--quiet` | Log quiet information |
| `FFSEND_VERBOSE` | `--verbose` | Log verbose information |
Some environment variables may be set at compile time to tweak some defaults.
| Variable | Description |
| :----------- | :------------------------------------- |
| `XCLIP_PATH` | Set fixed `xclip` binary path on Linux |
| `XSEL_PATH` | Set fixed `xsel` binary path on Linux |
At this time, no configuration or _dotfile_ file support is available.
This will be something added in a later release.
### Binary for each subcommand: `ffput`, `ffget`
`ffsend` supports having a separate binaries for single subcommands, such as
2019-03-17 16:56:18 +00:00
having `ffput` and `ffget` just for to upload and download using `ffsend`.
This allows simple and direct commands like:
```bash
ffput my-file.txt
ffget https://send.firefox.com/#sample-share-url
```
This works for a predefined list of binary names:
2019-03-17 16:56:18 +00:00
* `ffput``ffsend upload ...`
* `ffget``ffsend download ...`
* `ffdel``ffsend delete ...`
* _This list is defined in [`src/config.rs`](./src/config.rs) as `INFER_COMMANDS`_
2019-03-17 16:56:18 +00:00
You can use the following methods to set up these single-command binaries:
* Create a properly named symbolic link (recommended)
* Create a properly named hard link
* Clone the `ffsend` binary, and rename it
On Linux and macOS you can use the following command to set up symbolic links in
the current directory:
```bash
ln -s $(which ffsend) ./ffput
ln -s $(which ffsend) ./ffget
```
Support for this feature is only available when `ffsend` is compiled with the
[`infer-command`](#compile-features--use-flags) feature flag.
This is usually enabled by default.
To verify support is available with an existing installation, make sure the
feature is listed when invoking `ffsend debug`.
Note that the `snap` package does currently not support this due to how this
package format works.
2019-03-19 23:20:06 +00:00
### Scriptability
`ffsend` is optimized for use in automated scripts. It provides some specialized
arguments to control `ffsend` without user interaction.
- `--no-interact` (`-I`): do not allow user interaction. For prompts not having
a default value, the application will quit with an error, unless `--yes`
or `--force` is provided.
2019-03-19 23:23:15 +00:00
This should **always** be given when using automated scripting.
Example: when uploading a directory, providing this flag will stop the
2019-03-19 23:20:06 +00:00
archive question prompt form popping up, and will archive the directory as
default option.
2019-03-19 23:23:15 +00:00
- `--yes` (`-y`): assume the yes option for yes/no prompt by default.
Example: when downloading a file that already exists, providing this flag
2019-03-19 23:20:06 +00:00
will assume yes when asking to overwrite a file.
- `--force` (`-f`): force to continue with the action, skips any warnings that
2019-03-19 23:23:15 +00:00
would otherwise quit the application.
Example: when uploading a file that is too big, providing this flag will
2019-03-19 23:20:06 +00:00
ignore the file size warning and forcefully continues.
2019-03-19 23:23:15 +00:00
- `--quiet` (`-q`): be quiet, print as little information as possible.
Example: when uploading a file, providing this flag will only output the
2019-03-19 23:20:06 +00:00
final share URL.
2019-03-19 23:23:15 +00:00
Generally speaking, use the following rules when automating:
- Always provide `--no-interact` (`-I`).
- Provide any combination of `--yes` (`-y`) and `--force` (`-f`) for actions you
want to complete no matter what.
- When passing share URLs along, provide the `--quiet` (`-q`) flag, when
uploading for example.
2019-03-19 23:20:06 +00:00
These flags can also automatically be set by defining environment variables as
2019-03-19 23:23:15 +00:00
specified here:
2019-03-19 23:20:06 +00:00
[» Configuration and environment](#configuration-and-environment)
2019-03-19 23:23:15 +00:00
Here are some examples commands in `bash`:
2019-03-19 23:20:06 +00:00
```bash
# Stop on error
set -e
# Upload a file
# -I: no interaction
# -y: assume yes
# -q: quiet output, just return the share link
URL=$(ffsend -Iy upload -q my-file.txt)
# Render file information
# -I: no interaction
# -f: force, just show the info
ffsend -If info $URL
# Set a password for the uploaded file
ffsend -I password $URL --password="secret"
# Use the following flags automatically from now on
# -I: no interaction
# -f: force
# -y: yes
export FFSEND_NO_INTERACT=1 FFSEND_FORCE=1 FFSEND_YES=1
# Download the uploaded file, overwriting the local variant due to variables
2019-03-19 23:23:15 +00:00
ffsend download $URL --password="secret"
2019-03-19 23:20:06 +00:00
```
2019-03-19 23:23:15 +00:00
For more information on these arguments, invoke `ffsend help` and check out:
2019-03-19 23:20:06 +00:00
[» Configuration and environment](#configuration-and-environment)
2019-03-19 23:23:15 +00:00
For other questions regarding automation or feature requests, be sure to
2019-03-19 23:20:06 +00:00
[open](https://github.com/timvisee/ffsend/issues/) an issue.
2018-05-19 17:33:06 +00:00
## Security
In short; the `ffsend` tool and the [Send][send] service can be considered
secure, and may be used to share sensitive files. Note though that the
created share link for an upload will allow anyone to download the file.
Make sure you don't share this link with unauthorized people.
For more detailed information on encryption, please read the rest of the
paragraphs in this security section.
_Note: even though the encryption method is considered secure, this `ffsend`
tool does not provide any warranty in any way, shape or form for files that
somehow got decrypted without proper authorization._
#### Client side encryption
`ffsend` uses client side encryption, to ensure your files are securely
encrypted before they are uploaded to the remote host. This makes it impossible
for third parties to decrypt your file without having the secret (encryption
key). The file and its metadata are encrypted using `128-bit AES-GCM`, and a
2018-05-19 17:33:06 +00:00
`HMAC SHA-256` signing key is used for request authentication.
This is consistent with the encryption documentation provided by the
[Send][send] service, `ffsend` is a tool for.
A detailed list on the encryption/decryption steps, and on what encryption is
exactly used can be found [here][send-encryption] in the official service
documentation.
#### Note on share link security
The encryption secret, that is used to decrypt the file when downloading,
is included in the share URL behind the `#` (hash). This secret is never sent
the remote server directly when using the share link in your browser.
It would be possible however for a webpage to load some malicious JavaScript
snippet that eventually steals the secret from the link once the page is loaded.
Although this scenario is extremely unlikely, there are some options to prevent
this from happening:
- Only use this `ffsend` tool, do not use the share link in your browser.
- Add additional protection by specifying a password using `--password` while
uploading, or using the `password` subcommand afterwards.
- Host a secure [Send][send] service instance yourself.
A complete overview on encryption can be found in the official service
documentation [here][send-encryption].
2018-05-17 22:08:05 +00:00
## Help
```
$ ffsend help
2019-03-25 20:01:52 +00:00
ffsend 0.2.42
2019-03-18 15:31:43 +00:00
Tim Visee <3a4fb3964f@sinenomine.email>
2018-05-19 17:33:06 +00:00
Easily and securely share files from the command line.
2018-05-17 22:08:05 +00:00
A fully featured Firefox Send client.
USAGE:
ffsend [FLAGS] [OPTIONS] [SUBCOMMAND]
FLAGS:
-f, --force Force the action, ignore warnings
-h, --help Prints help information
-i, --incognito Don't update local history for actions
-I, --no-interact Not interactive, do not prompt
2018-11-29 08:39:34 +00:00
-q, --quiet Produce output suitable for logging and automation
2018-05-17 22:08:05 +00:00
-V, --version Prints version information
-v, --verbose Enable verbose information and logging
-y, --yes Assume yes for prompts
OPTIONS:
2019-03-18 15:31:43 +00:00
-A, --api <VERSION> Server API version to use, '-' to lookup [env: FFSEND_API]
--basic-auth <USER:PASSWORD> HTTP basic authentication credentials [env: FFSEND_BASIC_AUTH]
2018-11-20 12:06:55 +00:00
-H, --history <FILE> Use the specified history file [env: FFSEND_HISTORY]
-t, --timeout <SECONDS> Request timeout (0 to disable) [env: FFSEND_TIMEOUT]
-T, --transfer-timeout <SECONDS> Transfer timeout (0 to disable) [env: FFSEND_TRANSFER_TIMEOUT]
2018-05-17 22:08:05 +00:00
SUBCOMMANDS:
upload Upload files [aliases: u, up]
download Download files [aliases: d, down]
debug View debug information [aliases: dbg]
delete Delete a shared file [aliases: del]
exists Check whether a remote file exists [aliases: e]
2019-03-18 15:31:43 +00:00
generate Generate assets [aliases: gen]
2018-05-17 22:08:05 +00:00
help Prints this message or the help of the given subcommand(s)
history View file history [aliases: h]
info Fetch info about a shared file [aliases: i]
parameters Change parameters of a shared file [aliases: params]
password Change the password of a shared file [aliases: pass, p]
version Determine the Send server version [aliases: v]
2018-05-17 22:08:05 +00:00
The public Send service that is used as default host is provided by Mozilla.
This application is not affiliated with Mozilla, Firefox or Firefox Send.
```
2018-06-01 14:14:42 +00:00
## Special thanks
- to [Mozilla][mozilla] for building and hosting the amazing
[Firefox Send][send] service
- to everyone involved with [asciinema][asciinema] and [svg-term][svg-term] for
providing tools to make great visual demos
- to everyone involved in all crate dependencies used
2018-05-17 22:08:05 +00:00
## License
This project is released under the GNU GPL-3.0 license.
2018-05-18 12:45:00 +00:00
Check out the [LICENSE](LICENSE) file for more information.
2018-05-17 22:08:05 +00:00
[usage-demo-asciinema]: https://asciinema.org/a/182225
[usage-demo-svg]: https://cdn.rawgit.com/timvisee/ffsend/6e8ef55b/res/demo.svg
2018-05-17 22:08:05 +00:00
[firefox]: https://firefox.com/
[git]: https://git-scm.com/
2018-05-17 22:30:26 +00:00
[libressl]: https://libressl.org/
[mozilla]: https://mozilla.org/
2018-05-17 22:08:05 +00:00
[openssl]: https://www.openssl.org/
[openssl-windows-installer]: https://slproweb.com/download/Win64OpenSSL_Light-1_1_0j.exe
2018-05-17 22:08:05 +00:00
[rust]: https://rust-lang.org/
[rustup]: https://rustup.rs/
[send]: https://send.firefox.com/
2018-05-19 17:33:06 +00:00
[send-encryption]: https://github.com/mozilla/send/blob/master/docs/encryption.md
2018-06-01 14:14:42 +00:00
[asciinema]: https://asciinema.org/
[svg-term]: https://github.com/marionebl/svg-term-cli
[github-releases]: https://github.com/timvisee/ffsend/releases
2018-05-31 20:33:09 +00:00
[github-latest-release]: https://github.com/timvisee/ffsend/releases/latest
2019-01-12 22:19:11 +00:00
[aur-ffsend]: https://aur.archlinux.org/packages/ffsend/
2019-03-04 15:33:46 +00:00
[aur-ffsend-git]: https://aur.archlinux.org/packages/ffsend-git/
[snapcraft-ffsend]: https://snapcraft.io/ffsend
[homebrew]: https://brew.sh/
[wsl]: https://docs.microsoft.com/en-us/windows/wsl/install-win10
2019-03-13 17:56:04 +00:00
[docker-hub-ffsend]: https://hub.docker.com/r/timvisee/ffsend
2019-03-15 00:16:41 +00:00
[scoop-install]: https://scoop.sh/#installs-in-seconds