# tmphost.io CLI

> The `tmphost` command uploads files from disk to a temporary public folder and prints their URLs. Its `file` commands mirror the actions of the MCP file tool (https://tmphost.io/docs/mcp.md).

HTML version: https://tmphost.io/docs/cli/ · Docs overview: https://tmphost.io/docs.md · MCP tools: https://tmphost.io/docs/mcp.md

## Why agents should prefer the CLI

The CLI reads and writes files on disk, so file content never enters the model's context: uploading a 5 MB PDF or a whole `dist/` folder costs a command and a few lines of output. Through MCP the same bytes would be written out as a tool argument, as text or as base64. Whenever the agent can run shell commands, use the CLI.

## Local paths

The CLI works with paths on disk in both directions: `upload` takes any number of local files and directories, from anywhere on disk, and `download` writes to the local path given with `-o`. The bytes go straight between the disk and tmphost.io, never through the model.

### Upload: where local files land in the folder

| Command | Paths in the folder |
| --- | --- |
| `tmphost file upload build/out/report.pdf` | `report.pdf` (the base name) |
| `tmphost file upload ~/notes/a.md ./b.txt` | `a.md`, `b.txt` |
| `tmphost file upload site` | `site/index.html`, `site/css/app.css` |
| `tmphost file upload site/` | `index.html`, `css/app.css` |
| `tmphost file upload site/ --path v2` | `v2/index.html`, `v2/css/app.css` |
| `tmphost file upload out.txt --path logs --name today.txt` | `logs/today.txt` |

Symlinks to files are followed; other non-regular files are skipped.

### Download: to any local path

```console
$ tmphost file download --id p3n8w1cd --path assets style.css -o build/cache/style.css
Downloaded assets/style.css (3.0 KiB) to build/cache/style.css
$ tmphost file download --id p3n8w1cd index.html
Downloaded index.html (1.3 KiB) to index.html
```

`--path` is the file's directory inside the folder; `-o` is where it goes on disk, and its directory must already exist. Without `-o` the file is written to `./<fileName>`. An existing file is kept unless `--force` is given.

## Install

macOS and Linux (amd64, arm64):

```sh
curl -fsSL https://raw.githubusercontent.com/tmphost/tmphost/main/install.sh | sh
```

Windows (PowerShell):

```powershell
irm https://raw.githubusercontent.com/tmphost/tmphost/main/install.ps1 | iex
```

Both download the latest release, check it against `checksums.txt` and install `tmphost` to `/usr/local/bin` when writable, or `~/.local/bin` (Windows: `%LOCALAPPDATA%\tmphost\bin`, added to the user PATH). Set `TMPHOSTIO_VERSION=v1.2.3` for a specific release or `TMPHOSTIO_INSTALL_DIR` for another directory.

## Sign in

```console
$ tmphost login --server https://app.tmphost.io
Logged in to https://app.tmphost.io as agent@example.com (250/250 credits)
```

`login` opens the browser to approve the CLI (OAuth 2.1 with PKCE; the URL is printed too, in case the browser does not open) and waits up to 5 minutes. The tokens are saved to `$TMPHOSTIO_CONFIG`, or `tmphost/config.json` in the user config directory, readable only by the user, and refreshed automatically. Later commands use the same server.

## Upload

The ids, times and URLs below are examples; take the real ones from the output.

### One file, in a new folder

```console
$ tmphost file upload report.pdf
Uploading 1 files (cost: 3 credits)
https://k7q2m9xa.file.tmphost.io/report.pdf

id:      k7q2m9xa
url:     https://k7q2m9xa.file.tmphost.io/
expires: 2026-10-19 21:38 UTC (in 30m)
```

A new folder lives 30 minutes by default. A 2.4 MB file costs 3 credits per started 30 minutes.

### A directory, with a TTL

```console
$ tmphost file upload dist/ --ttl 2h
Uploading 3 files (cost: 12 credits)
https://p3n8w1cd.file.tmphost.io/index.html
https://p3n8w1cd.file.tmphost.io/assets/app.js
https://p3n8w1cd.file.tmphost.io/assets/style.css

id:      p3n8w1cd
url:     https://p3n8w1cd.file.tmphost.io/
expires: 2026-10-19 23:08 UTC (in 2h0m)
```

`dist/` (or `.`) uploads the directory's contents, like rsync, so `index.html` lands at the root and the folder URL serves the site. `dist` without the slash keeps the name as a prefix: `dist/index.html`. Directories are uploaded recursively.

### Into an existing folder

```console
$ tmphost file upload notes.txt --id p3n8w1cd --path docs --name readme.txt
Uploading 1 files (cost: 4 credits)
https://p3n8w1cd.file.tmphost.io/docs/readme.txt

id:      p3n8w1cd
url:     https://p3n8w1cd.file.tmphost.io/
expires: 2026-10-19 23:08 UTC (in 1h56m)
```

`--id` adds to a folder, and a file already at the same path is replaced in place: same URL, same expiry. `--path` puts files in a directory inside the folder; `--name` renames a single file. `--ttl` only applies to a new folder.

### JSON output, for agents

Add `--json` to any command to print the same fields as the MCP tool, with no progress lines:

```console
$ tmphost file upload dist/ --ttl 2h --json
{
  "id": "p3n8w1cd",
  "url": "https://p3n8w1cd.file.tmphost.io/",
  "expiresAt": "2026-10-19T23:08:00Z",
  "creditsSpent": 12,
  "files": [
    {
      "fileName": "index.html",
      "path": "",
      "size": 1342,
      "url": "https://p3n8w1cd.file.tmphost.io/index.html"
    },
    {
      "fileName": "app.js",
      "path": "assets",
      "size": 20480,
      "url": "https://p3n8w1cd.file.tmphost.io/assets/app.js"
    },
    {
      "fileName": "style.css",
      "path": "assets",
      "size": 3120,
      "url": "https://p3n8w1cd.file.tmphost.io/assets/style.css"
    }
  ]
}
```

For a single file, `url`, `fileName`, `path` and `size` describe that file, as in the MCP `upload` result.

## List a folder

```console
$ tmphost file get --id p3n8w1cd
FILE NAME   PATH    SIZE      URL
index.html          1.3 KiB   https://p3n8w1cd.file.tmphost.io/index.html
app.js      assets  20.0 KiB  https://p3n8w1cd.file.tmphost.io/assets/app.js
style.css   assets  3.0 KiB   https://p3n8w1cd.file.tmphost.io/assets/style.css
readme.txt  docs    28 B      https://p3n8w1cd.file.tmphost.io/docs/readme.txt

id:      p3n8w1cd
url:     https://p3n8w1cd.file.tmphost.io/
expires: 2026-10-19 23:08 UTC (in 1h52m)
```

## Print a URL

```console
$ tmphost file url --id p3n8w1cd --path docs readme.txt
https://p3n8w1cd.file.tmphost.io/docs/readme.txt
$ tmphost file url --id p3n8w1cd --path assets
https://p3n8w1cd.file.tmphost.io/assets/
```

A folder (`--id`), a directory (`--path`, ending with `/`) or a file. The file does not have to exist yet.

## Download

```console
$ tmphost file download --id p3n8w1cd --path docs readme.txt -o readme.txt
Downloaded docs/readme.txt (28 B) to readme.txt
$ tmphost file download --id p3n8w1cd --path docs readme.txt -o - --json --format textContent
{
  "id": "p3n8w1cd",
  "fileName": "readme.txt",
  "path": "docs",
  "size": 28,
  "textContent": "Build notes: see index.html\n"
}
```

Download to a file with `-o` so the content stays on disk; an existing file is kept unless `--force` is given. `-o -` writes to stdout, and with `--json` the content goes in `base64Content`, or in `textContent` with `--format textContent`.

## Manage folders and the account

```console
$ tmphost file ls
ID        EXPIRES IN  URL
p3n8w1cd  1h50m       https://p3n8w1cd.file.tmphost.io/
k7q2m9xa  18m         https://k7q2m9xa.file.tmphost.io/
$ tmphost file rm --id p3n8w1cd docs/readme.txt
Deleted docs/readme.txt from folder p3n8w1cd.
$ tmphost file rm --id k7q2m9xa
Deleted folder k7q2m9xa.
$ tmphost whoami
Email:      agent@example.com
Name:       Agent
Credits:    231/250
Renews at:  2026-11-18 00:00 UTC
$ tmphost logout
Logged out.
```

## Commands

| Command | Description |
| --- | --- |
| `tmphost login [--server URL]` | Sign in with the browser. |
| `tmphost logout` | Forget the saved tokens. |
| `tmphost whoami` | Show the user, credits and renewal time. |
| `tmphost file upload <local path>... [--id ID \| --ttl 30m] [--path DIR] [--name NAME]` | Upload files and print their URLs and the folder id. |
| `tmphost file download --id ID [--path DIR] <fileName> [-o OUT] [--force] [--format FORMAT]` | Download a file (`-o -` for stdout). |
| `tmphost file get --id ID` | List a folder's files. |
| `tmphost file url --id ID [--path DIR] [fileName]` | Print a folder, directory or file URL. |
| `tmphost file ls` | List live folders. |
| `tmphost file rm --id ID [path]` | Delete a folder, or one file. |

Global flags: `--json` prints JSON, `--server` (or `TMPHOSTIO_SERVER`) picks the server, `--version` prints the version. Tokens are only sent to the server that issued them.

## Paths and cost

Paths are at most 5 directories deep, with no `.` or `..` segments and no backslashes; the CLI checks them before anything is sent. Each file costs 1 credit per started MB of its size per started 30 minutes of the folder's lifetime, and `upload` checks the total against the account's credits before it uploads anything.