Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
ONESHOT(1)Aug(2026)					     ONESHOT(1)Aug(2026)

https://github.com/raphaelreyna/oneshot

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

SYNOPSIS
     oneshot [flags]... [file|dir|url]

DESCRIPTION
     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).

OPTIONS
     -B,  --allow-bots[=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 iMes-
     sage.  A client is considered to be a bot if the 'User-Agent'  header  con-
     tains either 'bot', 'Bot' or 'facebookexternalhit'.

     -a, --archive-method="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".

     -c, --cgi[=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

     --cgi-stderr=""	   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

     -C,  --cgi-strict[=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 at-
     tempts 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

     --custom-csrf-token=""	 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

     -d, --dir=""      Working directory  for  the  executable	or  when  saving
     files.  Defaults to where oneshot was called.  Setting this flag does noth-
     ing  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

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

     -F, --exit-on-fail[=false]      Exit as soon as client disconnects  regard-
     less  if  file  was transferred succesfully.  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  re-
     ceive a 410 Gone status immediately; otherwise, client waits in a queue and
     is served if all previous clients fail or drop out.

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

     -H,  --header=[]	    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

     -h, --help[=false]      help for oneshot

     -W, --hidden-password[=false]	Prompt for password for basic  authenti-
     cation.   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

     --host=""	    Host specifies the TCP address for the server to listen on.

     -M,  --mdns[=false]       Register  oneshot as an mDNS (bonjour/avahi) ser-
     vice.

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

     -n, --name=""	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

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

     -D,  --no-download[=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.

     -L,  --no-unix-eol-norm[=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  pre-
     vents oneshot from doing the replacement CR+LF -> LF.  This flag does noth-
     ing  if  both  the  -u, --upload and --upload-input flags are not set.  See
     also: -u, --upload; --upload-input

     -P, --password=""	    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.

     -w, --password-file=""	 File containing password for basic  authentica-
     tion.   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.

     -p, --port="8080"	    Port to bind to.

     -q,  --quiet[=false]	Don't  show info messages.  Use -Q, --silent in-
     stead to suppress error messages as well.

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

     -R, --replace-header[=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

     -s, --shell="/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

     -S, --shell-command[=false]      Run a shell command in a flexible CGI  en-
     vironment.   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

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

     -T, --ss-tls[=false]      Generate  and  use  a  self-signed  TLS	certifi-
     cate/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

     --status-code=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

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

     --tls-cert=""	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 pro-
     vided using the --tls-key flag.  See also: --tls-key ; -T, --ss-tls

     --tls-key=""      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  pro-
     vided using the --tls-cert flag.  See also: --tls-cert ; -T, --ss-tls

     -u,  --upload[=false]	Receive a file, allow client to send text or up-
     load 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  ar-
     gument  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

     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).

     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  multi-
     part/form-data) of any POST request sent to "/"

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

     --upload-file[=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

     --upload-html=""	   Path to html file to present to clients attempting to
     upload.  The file may be a Go HTML temlate. Two boolean  values  '.FileSec-
     tion' and '.InputSection' and a string value ' .CSRFToken ' are made avail-
     able to the template.  The boolean values ' .FileSection ' and ' .InputSec-
     tion  '  reflect  the  usage  of the -u, --upload; --upload-input and --up-
     load-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

     --upload-input[=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:  --up-
     load-file; -u, --upload; -L, --no-unix-eol-norm

     -U,  --username=""       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 en-
     ter any password.

     -v, --version[=false]	Version and other info.

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

HISTORY
     1-Aug-2026 Auto generated by spf13/cobra

							     ONESHOT(1)Aug(2026)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=oneshot&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help