oneshot.1

.nh
.TH ONESHOT(1)Apr 2021
https://github.com/forestnode-io/oneshot

.SH NAME
.PP
oneshot \- A single\-fire first\-come\-first\-serve HTTP server.


.SH SYNOPSIS
.PP
\fBoneshot [flags]... [file|dir|url]\fP


.SH DESCRIPTION
.PP
Transfer files and data easily between your computer and any browser or HTTP client.
The first client to connect is given the file or uploads a file, all others receive an HTTP 410 Gone response code.
Directories will automatically be archived before being sent (see \-a, \-\-archive\-method for more information).


.SH OPTIONS
.PP
\fB\-B\fP, \fB\-\-allow\-bots\fP[=false]
	Allow bots to attempt download.
By default, bots are prevented from attempting the download; this is required to allow links to be sent over services that provide previews such as Apple iMessage.
A client is considered to be a bot if the 'User\-Agent' header contains either 'bot', 'Bot' or 'facebookexternalhit'.

.PP
\fB\-a\fP, \fB\-\-archive\-method\fP="tar.gz"
	Which archive method to use when sending directories.
Recognized values are "zip" and "tar.gz", any unrecognized values will default to "tar.gz".

.PP
\fB\-c\fP, \fB\-\-cgi\fP[=false]
	Run the given file in a forgiving CGI environment.
Setting this flag will override the \-u, \-\-upload flag.
See also: \-C, \-\-cgi\-strict ; \-s, \-\-shell\-command ; \-S, \-\-shell ; \-R, \-\-replace\-headers ; \-H, \-\-header ; \-E, \-\-env ; \-\-cgi\-stderr

.PP
\fB\-\-cgi\-stderr\fP=""
	Where to redirect executable's stderr when running in CGI mode.
See also: \-c, \-\-cgi ; \-C, \-\-cgi\-strict ; \-s, \-\-shell\-command ; \-S, \-\-shell ; \-R, \-\-replace\-headers ; \-H, \-\-header ; \-\-cgi\-stderr

.PP
\fB\-C\fP, \fB\-\-cgi\-strict\fP[=false]
	Run the given file in a CGI environment.
Setting this flag overrides the \-c, \-\-cgi flag and acts as a modifier to the \-S, \-\-shell\-command flag.
If this flag is set, the file passed to oneshot will be run in a strict CGI environment; i.e. if the executable attempts to send invalid headers, oneshot will exit with an error.
If you instead wish to simply send an executables stdout without worrying about setting headers, use the \-c, \-\-cgi flag.
If the \-S, \-\-shell\-command flag is used to pass a command, this flag has no effect.
Setting this flag will override the \-u, \-\-upload flag.
See also: \-c, \-\-cgi ; \-s, \-\-shell\-command ; \-S, \-\-shell ; \-R, \-\-replace\-headers ; \-H, \-\-header ; \-E, \-\-env ; \-\-cgi\-stderr

.PP
\fB\-\-custom\-csrf\-token\fP=""
	Use a custom CSRF token for uploads.
This flag does nothing if none of the \-u, \-\-upload, \-\-upload\-input or \-\-upload\-file flags are set.
See also: \-u, \-\-upload; \-\-upload\-input; \-\-no\-csrf\-token

.PP
\fB\-d\fP, \fB\-\-dir\fP=""
	Working directory for the executable or when saving files.
Defaults to where oneshot was called.
Setting this flag does nothing unless either the \-c, \-\-cgi or \-S, \-\-shell\-command flag is set.
See also: \-c, \-\-cgi ; \-C, \-\-cgi\-strict ; \-s, \-\-shell\-command ; \-S, \-\-shell ; \-R, \-\-replace\-headers ; \-H, \-\-header ; \-\-cgi\-stderr

.PP
\fB\-E\fP, \fB\-\-env\fP=[]
	Environment variable to pass on to the executable.
Setting this flag does nothing unless either the \-c, \-\-cgi or \-S, \-\-shell\-command flag is set.
Must be in the form 'KEY=VALUE'.
See also: \-c, \-\-cgi ; \-C, \-\-cgi\-strict ; \-s, \-\-shell\-command ; \-S, \-\-shell ; \-R, \-\-replace\-headers ; \-H, \-\-header ; \-\-cgi\-stderr

.PP
\fB\-F\fP, \fB\-\-exit\-on\-fail\fP[=false]
	Exit as soon as client disconnects regardless if file was transferred successfully.
By default, oneshot will exit once the client has downloaded the entire file.
If using authentication, setting this flag will cause oneshot to exit if client provides wrong / no credentials.
If set, once the first client connects, all others will receive a 410 Gone status immediately;
otherwise, client waits in a queue and is served if all previous clients fail or drop out.

.PP
\fB\-e\fP, \fB\-\-ext\fP=""
	Extension of file presented to client.
If not set, either no extension or the extension of the file will be used,
depending on if a file was given.

.PP
\fB\-H\fP, \fB\-\-header\fP=[]
	HTTP header to send to client.
Setting a value for 'Content\-Type' will override the \-M, \-\-mime flag.
To allow executable to override header see the \-R, \-\-replace\-headers flag.
Must be in the form 'KEY: VALUE'.
See also: \-c, \-\-cgi ; \-C, \-\-cgi\-strict ; \-s, \-\-shell\-command ; \-S, \-\-shell ; \-R, \-\-replace\-headers ; \-E, \-\-env ; \-\-cgi\-stderr

.PP
\fB\-h\fP, \fB\-\-help\fP[=false]
	help for oneshot

.PP
\fB\-W\fP, \fB\-\-hidden\-password\fP[=false]
	Prompt for password for basic authentication.
If a username is not also provided using the \-U, \-\-username flag then the client may enter any username.
Takes precedence over the \-w, \-\-password\-file flag

.PP
\fB\-\-host\fP=""
	Host specifies the TCP address for the server to listen on.

.PP
\fB\-M\fP, \fB\-\-mdns\fP[=false]
	Register oneshot as an mDNS (bonjour/avahi) service.

.PP
\fB\-m\fP, \fB\-\-mime\fP=""
	MIME type of file presented to client.
If not set, either no MIME type or the mime/type of the file will be user,
depending on of a file was given.

.PP
\fB\-n\fP, \fB\-\-name\fP=""
	Name of file presented to client or if uploading, the name of the file saved to this computer.
If not set, either a random name or the name of the file will be used,
depending on if a file was given.
See also: \-u, \-\-upload ; \-\-upload\-input ; \-\-upload\-file

.PP
\fB\-\-no\-csrf\-token\fP[=false]
	Do not use a CSRF token for uploads.
This flag does nothing if none of the \-u, \-\-upload, \-\-upload\-input or \-\-upload\-file flags are set.
See also: \-u, \-\-upload; \-\-upload\-input

.PP
\fB\-D\fP, \fB\-\-no\-download\fP[=false]
	Don't trigger browser download client side.
If set, the "Content\-Disposition" header used to trigger downloads in the clients browser won't be sent.

.PP
\fB\-L\fP, \fB\-\-no\-unix\-eol\-norm\fP[=false]
	Don't normalize end\-of\-line chars to unix style on user input.
Most browsers send DOS style (CR+LF) end\-of\-line characters when submitting user form input; setting this flag to true prevents oneshot from doing the replacement CR+LF \-> LF.
This flag does nothing if both the \-u, \-\-upload and \-\-upload\-input flags are not set.
See also: \-u, \-\-upload; \-\-upload\-input

.PP
\fB\-P\fP, \fB\-\-password\fP=""
	Password for basic authentication.
If an empty password ("") is set then a random secure will be used.
If a username is not also provided using the \-U, \-\-username flag then the client may enter any username.
If either the \-W, \-\-hidden\-password or \-w, \-\-password\-file flags are set, this flag will be ignored.

.PP
\fB\-w\fP, \fB\-\-password\-file\fP=""
	File containing password for basic authentication.
If a username is not also provided using the \-U, \-\-username flag then the client may enter any username.
If the \-W, \-\-hidden\-password flag is set, this flags will be ignored.

.PP
\fB\-p\fP, \fB\-\-port\fP="8080"
	Port to bind to.

.PP
\fB\-q\fP, \fB\-\-quiet\fP[=false]
	Don't show info messages.
Use \-Q, \-\-silent instead to suppress error messages as well.

.PP
\fB\-r\fP, \fB\-\-redirect\fP[=false]
	Redirect the first client to connect to the URL given as the first argument to oneshot.
See also: \-\-status\-code

.PP
\fB\-R\fP, \fB\-\-replace\-header\fP[=false]
	Allow executable to override headers set by  the \-H, \-\-header flag.
Setting this flag does nothing unless either the \-c, \-\-cgi or \-S, \-\-shell\-command flag is set.
See also: \-c, \-\-cgi ; \-C, \-\-cgi\-strict ; \-s, \-\-shell\-command ; \-S, \-\-shell ; \-H, \-\-header ; \-E, \-\-env ; \-\-cgi\-stderr

.PP
\fB\-s\fP, \fB\-\-shell\fP="/bin/sh"
	Shell that should be used when running a shell command.
Setting this flag does nothing if the \-S, \-\-shell\-command flag is not set.
See also: \-c, \-\-cgi ; \-C, \-\-cgi\-strict ; \-s, \-\-shell\-command ; \-R, \-\-replace\-headers ; \-H, \-\-header ; \-E, \-\-env ; \-\-cgi\-stderr

.PP
\fB\-S\fP, \fB\-\-shell\-command\fP[=false]
	Run a shell command in a flexible CGI environment.
If you wish to run the command in a strict CGI environment where oneshot exits upon detecting invalid headers, use the \-C, \-\-strict\-cgi flag as well.
If this flag is used to pass a shell command, then any file passed to oneshot will be ignored.
Setting this flag will override the \-u, \-\-upload flag.
See also: \-c, \-\-cgi ; \-C, \-\-cgi\-strict ; \-S, \-\-shell ; \-R, \-\-replace\-headers ; \-H, \-\-header ; \-E, \-\-env ; \-\-cgi\-stderr

.PP
\fB\-Q\fP, \fB\-\-silent\fP[=false]
	Don't show info and error messages.
Use \-q, \-\-quiet instead to suppress info messages only.

.PP
\fB\-T\fP, \fB\-\-ss\-tls\fP[=false]
	Generate and use a self\-signed TLS certificate/key pair for HTTPS.
A new certificate/key pair is generated for each running instance of oneshot.
To use your own certificate/key pair, use the \-\-tls\-cert and \-\-tls\-key flags.
See also: \-\-tls\-key ; \-T, \-\-ss\-tls

.PP
\fB\-\-status\-code\fP=303
	Sets the HTTP response status code when performing a redirect.
This flag does nothing if not redirecting to a different URL.
See also: \-r, \-\-redirect

.PP
\fB\-t\fP, \fB\-\-timeout\fP=0s
	How long to wait for client.
A value of zero will cause oneshot to wait indefinitely.

.PP
\fB\-\-tls\-cert\fP=""
	Certificate file to use for HTTPS.
If the empty string ("") is passed to both this flag and \-\-tls\-key, then oneshot will generate, self\-sign and use a TLS certificate/key pair.
Key file must also be provided using the \-\-tls\-key flag.
See also: \-\-tls\-key ; \-T, \-\-ss\-tls

.PP
\fB\-\-tls\-key\fP=""
	Key file to use for HTTPS.
If the empty string ("") is passed to both this flag and \-\-tls\-cert, then oneshot will generate, self\-sign and use a TLS certificate/key pair.
Cert file must also be provided using the \-\-tls\-cert flag.
See also: \-\-tls\-cert ; \-T, \-\-ss\-tls

.PP
\fB\-u\fP, \fB\-\-upload\fP[=false]
	Receive a file, allow client to send text or upload a file to your computer.
Setting this flag will cause oneshot to serve up a minimalistic web\-page that prompts the client to either upload a file or enter text.
To only allow for a file or user input and not both, see the \-\-upload\-file and \-\-upload\-input flags.
By default if no path argument is given, the file will be sent to standard out (nothing else will be printed to standard out, this is useful for when you wish to pipe or redirect the file uploaded by the client).
If a path to a directory is given as an argument (or the \-d, \-\-dir flag is set), oneshot will save the file to that directory using either the files original name or the one set by the \-n, \-\-name flag.
If both the \-d, \-\-dir flag is set and a path is given as an argument, then the path from \-d, \-\-dir is prepended to the one from the argument.
See also: \-\-upload\-file; \-\-upload\-input; \-L, \-\-no\-unix\-eol\-norm

.PP
Example: Running "oneshot \-u \-d /foo ./bar/baz" will result in the clients uploaded file being saved to directory /foo/bar/baz.
Example: Running "oneshot \-u \-n baz ./bar" will result in the clients uploaded file being saved to directory ./bar with the name baz (so ./bar/baz).

.PP
This flag actually exposes an upload API as well.
Oneshot will save either the entire body, or first file part (if the Content\-Type is set to multipart/form\-data) of any POST request sent to "/"

.PP
Example: Running "curl \-d 'Hello World!' localhost:8080" will send 'Hello World!' to oneshot.

.PP
\fB\-\-upload\-file\fP[=false]
	Receive a file, allow client to upload a file to your computer.
Setting both this flag and \-\-upload\-input is equivalent to setting the \-u, \-\-upload flag.
For more information see the \-u, \-\-upload flag documentation.
See also: \-\-upload\-input; \-u, \-\-upload

.PP
\fB\-\-upload\-html\fP=""
	Path to html file to present to clients attempting to upload.
The file may be a Go HTML template. Two boolean values '.FileSection' and '.InputSection' and a string value ' .CSRFToken ' are made available to the template.
The boolean values ' .FileSection ' and ' .InputSection ' reflect the usage of the \-u, \-\-upload; \-\-upload\-input and \-\-upload\-file flags.
The string value ' .CSRFToken ' reflects the usage of the \-\-no\-csrf\-token and \-\-custom\-csrf\-token flags.
This flag does nothing if none of the \-u, \-\-upload, \-\-upload\-input or \-\-upload\-file flags are set.
See also: \-u, \-\-upload; \-\-upload\-input

.PP
\fB\-\-upload\-input\fP[=false]
	Receive text from a browser.
Setting both this flag and \-\-upload\-file is equivalent to setting the \-u, \-\-upload flag.
For more information see the \-u, \-\-upload flag documentation.
See also: \-\-upload\-file; \-u, \-\-upload; \-L, \-\-no\-unix\-eol\-norm

.PP
\fB\-U\fP, \fB\-\-username\fP=""
	Username for basic authentication.
If an empty username ("") is set then a random, easy to remember username will be used.
If a password is not also provided using either the \-P, \-\-password flag ; \-W, \-\-hidden\-password; or \-w, \-\-password\-file flags then the client may enter any password.

.PP
\fB\-v\fP, \fB\-\-version\fP[=false]
	Version and other info.

.PP
\fB\-J\fP, \fB\-\-wait\-for\-eof\fP[=false]
	Wait for EOF before starting HTTP(S) server if serving from stdin.
This flag does noting if not serving from stdin.


.SH HISTORY
.PP
14\-Apr\-2021 Auto generated by spf13/cobra