Dropstone CLI

Troubleshooting guide

Diagnose Dropstone CLI problems systematically. Collect the right information, find the logs, and isolate the cause before you contact support.

Most problems fall to one of four things: an old build, a stale cache, bad credentials, or the network. This page is the order to check them in, and what to collect when none of them is it.

For a specific error message, start with Common issues instead. For runtime behaviour and per-feature debugging, see CLI troubleshooting.

First three things to try

Run these before anything else. They resolve a surprising share of reports.

# 1. Get current
dropstone update

# 2. See what Dropstone is actually doing
dropstone --log-level DEBUG --print-logs
  1. If the failure happens mid-session and the cause is unclear, clear the cache and restart:
rm -rf ~/.cache/dropstone

On Windows, press WIN+R and delete %USERPROFILE%\.cache\dropstone.

Before you delete anything else

The three commands above are safe. Deleting ~/.local/share/dropstone is not — that is where your credentials and session history live. See Where state lives before removing that directory.

Where state lives

Everything Dropstone keeps on disk sits in two directories.

WhatmacOS / LinuxWindows
Credentials and sessions~/.local/share/dropstone/%USERPROFILE%\.local\share\dropstone
Logs~/.local/share/dropstone/log/%USERPROFILE%\.local\share\dropstone\log
Cache~/.cache/dropstone/%USERPROFILE%\.cache\dropstone

Inside the data directory:

  • auth.json — your credentials. Delete this only to force a clean sign-in.
  • log/ — timestamped logs. The ten most recent are kept.
  • project/ — session history, scoped per project.

A log file is named for when it was written, for example 2026-05-23T123456.log. The most recent one is the one you want.

Get a log that is worth reading

By default the log level is quiet. Two flags change that:

# Detailed output written to the log file
dropstone --log-level DEBUG

# The same output streamed to your terminal as it happens
dropstone --print-logs

Use both together when you want to watch the failure occur and still have the file afterwards.

If the problem is a crash on launch, --print-logs is the one that helps: the log file may not be written at all before the process dies, but stderr always is.

What to include in a report

A report with these five things usually needs one reply to resolve. A report without them usually needs four.

  1. The exact command you ran. Not a paraphrase — the literal line, including flags.

  2. What you expected, and what happened. Both halves. "It failed" does not narrow anything.

  3. Your version and platform.

    dropstone --version

    Plus your OS and version, and whether you are on native Windows or inside WSL.

  4. The relevant log excerpt. A few lines either side of the error, not the whole file. Redact anything sensitive — session logs can contain file paths and code.

  5. Whether it is reproducible. Always, sometimes, or once. "Sometimes" is worth saying; it points at timing or state rather than a bad input.

Send it to dropstone.io/contact.

Narrowing it down

If the cause is still not obvious, eliminate variables one at a time. Each of these removes a whole category.

Is it the project? Run Dropstone in an empty directory. If it works there, the problem is project-scoped — likely a config file, a rules file, or something in the repo the agent is reading.

Is it your config? Temporarily move dropstone.json aside and relaunch. See Configuration for where the global and project config files live.

Is it an MCP server? A server that hangs on startup will stall the whole session. List them and disable them, then re-enable one at a time:

dropstone mcp list

Is it the network? Corporate proxies are the most common cause of failures that look like something else. Check:

curl -I https://dropstone.io

If that fails or returns something unexpected, see Network and proxy. The usual fix is setting HTTPS_PROXY and, importantly, NO_PROXY=localhost,127.0.0.1 — Dropstone uses a local loopback during interactive sessions, and routing that through a proxy causes a loop.

Is it your credentials? Sign out and back in:

dropstone auth logout
dropstone auth login

Is it the terminal? On Linux, copy and paste need a clipboard utility installed. See CLI troubleshooting.

Is it Windows? Slow file access, terminal glitches, and path problems on native Windows usually disappear under WSL. See Windows and WSL.

Before you contact support

Ctrl+I