Handing files over, and showing them#
Asking the user for a file, or showing them one, when the caller has no terminal of its own: an agent, for instance. --pick prints the paths the user sends; --serve shows them a page. Without a terminal on standard input both detach, print one line of JSON, and are answered later with --resume, which waits for the answer. --status asks at once, as JSON, how the pick stands, and changes nothing; it still answers after --resume. --cancel ends the session, deleting its folder. All three take the resume token, not the one in the page’s address.
| Option | Argument | Default | Description |
|---|---|---|---|
--accept | string | require these content formats for this session, comma-separated: image/*, pdf, svg, stl, 3mf, docx, xlsx, grist, csv, json, ipynb, html, text, markdown | |
--pick | wait for the user to hand over files: Enter prints their paths and quits | ||
--pick-web | experimental file request with Choose files and Send buttons, without a terminal; implies –serve –pick; takes no input files | ||
--listen | string | "127.0.0.1:0" | with –pick-web, listen on IP:port (IPv6: [IP]:port); port 0 chooses a free port; wildcard requires –advertise-host |
--advertise-host | string | with –pick-web, use this IP or DNS name in the shared URL (no scheme, port, or path); defaults to the specific listen IP | |
--serve | show the viewer on a web page, from a temporary server on this machine | ||
--no-open | with –serve, print the page’s address without opening a browser | ||
--prompt | string | show this request to the user in a box, to say what to pick or look at | |
--prompt-loc | string | "bottom" | where the terminal prompt box goes: bottom or top (browser requests always appear above the viewer) |
--timeout | duration | with –serve or –pick, give up after this long (as 90s or 10m) | |
--resume | string | print the answer of a pick that was started without a terminal, by the token it printed; with –timeout, stop waiting after that long | |
--status | string | print, as JSON and at once, how a pick started without a terminal stands: waiting, picked, declined, timeout, closed, or failed; it waits for nothing and changes nothing | |
--cancel | string | end a session started without a terminal, by its resume token: stop its server and delete its folder, dropped files and answer alike |
Examples#
# Ask in the terminal
gloss --pick --prompt "Which report?"
# Ask in a browser, and print what is sent
gloss --serve --pick
# Ask for uploads over a specific LAN address
gloss --pick-web --listen 192.168.1.42:0 --timeout 10m
# Show the user a file
gloss --serve report.pdf
# Collect the answer of a detached pick, waiting for it
gloss --resume TOKEN
# Ask how a detached pick stands, at once, without disturbing it
gloss --status TOKEN
# End a detached session, and delete what was dropped
gloss --cancel TOKEN