# `zfin server`

Ask the shared server (`ZFIN_SERVER`) to refresh its own cache.

```
Usage: zfin server refresh SYMBOL [SYMBOL...]
```

Force-refreshes candle data in the **server's** cache, bypassing its
TTL. Nothing local changes -- your next normal run picks up the server's
new copy through the usual sync.

## Which side are you refreshing?

Two commands look similar and do opposite things:

| Command                       | Refreshes            | Goes through the server? |
|-------------------------------|----------------------|--------------------------|
| `zfin cache refresh SYMBOL`   | your **local** cache | No, deliberately         |
| `zfin server refresh SYMBOL`  | the **server's** cache | That is the point      |

Run [`zfin diagnose SYMBOL`](diagnose.md) first -- its `local` and
`server` lines say which side is actually behind, so you do not refresh
the wrong one.

## `moved` vs `unchanged`

The per-symbol result reports whether the newest bar actually **moved**,
not merely whether the fetch succeeded. A successful refresh that changes
nothing is the signature of a provider with no newer data -- which is
usually the finding you came for, so it is not reported as success.

```bash
zfin server refresh SPY AGG
```

```
Asking https://zfin.example.org to refresh 2 symbol(s)...
  SPY       moved     2026-08-19
  AGG       unchanged 2026-08-18

1 moved, 1 unchanged, 0 failed
Your local cache is untouched - a normal run will sync the new copy.
```

## Requirements and limits

- **`ZFIN_SERVER`** must be set, and **`ZFIN_SERVER_API_KEY`** when the
  server enforces one. Without a server configured there is nothing to
  ask, and the command says so rather than falling back to a local fetch.
- The server caps a single request at **25 symbols**.
- It **refuses a second concurrent refresh** rather than queueing it, so
  a refresh already in flight (a cron run, say) returns a conflict rather
  than doubling the provider load.

## See also

- [`diagnose`](diagnose.md) -- which tier is behind, before you pick a side.
- [`cache`](cache.md) -- `refresh` for the local cache instead.
- [Caching and data freshness](../../explanation/caching.md) -- the server as an optional second tier.
- [Environment variables](../config/environment.md) -- `ZFIN_SERVER`, `ZFIN_SERVER_API_KEY`.

---

[CLI command reference](index.md)