Skip to content
xPort

Share registry & JSON output

Every share you start (tunnel, file, folder, paste, receive) is recorded in a local share registry. It powers xport list, xport stop, and the machine-readable --json output used by scripts and (later) the desktop app.

Terminal window
xport list            # show all active shares
xport stop k7fz2      # stop a share by id
xport share ./file.zip  # explicit share command (file or folder)

xport list

Section titled “xport list”
       ____            _
 __  _|  _ \ ___  _ __| |_
 \ \/ / |_) / _ \| '__| __|
  >  <|  __/ (_) | |  | |_
 /_/\_\_|   \___/|_|   \__|


ID      MODE    URL                              LOCAL                 EXPIRES              ALIVE
k7fz2   file    https://k7fz2.xport.sh/report…   ~/Downloads/repo…     2026-10-24 12:00:00  ✓

Expired entries are pruned automatically. Shares whose owning process no longer runs are marked DEAD and cleaned up on the next run.

xport stop

Section titled “xport stop”

Stops a running share by its id: SIGTERM first, a short grace period, then SIGKILL. Works on shares started from any terminal or (soon) the desktop app, because all of them write to the same registry.

Detached shares

Section titled “Detached shares”

Any share can be started in the background with --detach: the CLI spawns a detached copy of itself, waits until the share shows up in this registry, prints the URL and exits — the share keeps running without the terminal. Its output goes to a log file at <state-dir>/logs/<id>.log (e.g. ~/.local/state/xport/logs/k7fz2.log, honouring XDG_STATE_HOME). Detached shares appear in xport list like any other share and are stopped with xport stop <id> (SIGTERM first, as usual). --json --detach returns one envelope with the url, pid and log path.

Share registry file

Section titled “Share registry file”

Stored at ~/.local/state/xport/shares.yaml (honours XDG_STATE_HOME). Written atomically and guarded by a lock, so multiple xport processes can share it safely:

shares:
  - id: k7fz2
    mode: file
    url: https://k7fz2.xport.sh/report.pdf
    local_path: /Users/you/Downloads/report.pdf
    port: 0
    created: 2026-10-23T12:00:00Z
    expires: 2026-10-24T12:00:00Z
    pid: 1234

JSON output

Section titled “JSON output”

Pass --json (or set XPORT_JSON=1) to get exactly one JSON object on stdout — no banner, no colors, no prompts:

Terminal window
xport ./report.pdf --json
{"ok":true,"mode":"file","id":"k7fz2","url":"https://k7fz2.xport.sh/report.pdf","expires":"2026-10-24T12:00:00Z","password":false,"local_path":"./report.pdf"}

Errors are reported the same way with a non-zero exit code:

{"ok":false,"error":"no such share: nonexistent"}

Passwords never appear in JSON output. xport list --json returns the pruned entries with an alive boolean per entry.

Planned

Section titled “Planned”
  • Server-side share lists per user — after xport login (OAuth), your shares sync to your account so any device (or the desktop app) can list and stop them.