Skip to main content
This guide covers running Hoard Agent as a standalone command-line program. This is the right path if you’re on Linux, want to script Hoard Agent, or just prefer the terminal.
Prefer a point-and-click setup? See the Hoard Desktop Quick Start instead. Hoard Desktop handles account connection, downloads, and auto-start for you.

​
What Hoard Agent does

Hoard Agent is the same binary that Hoard Desktop manages for you, just without the GUI wrapper. It runs in your terminal, syncs your TCGplayer inventory on a schedule, and updates your prices. You manage starting, stopping, and auto-start yourself.

​
Requirements

  • A computer that stays on during sync times (Mac, Windows, or Linux)
  • A TCGplayer seller account (Level 4+)
  • A Hoard subscription (Gold, Platinum, or Diamond) with API key
If Chrome isn’t installed, Hoard Agent downloads a compatible Chromium automatically on first run (~200MB, one time).

​
Download

Get Hoard Agent from the Hoard setup page — expand Advanced: manual agent setup (terminal). You’ll download two things:
  • hoard-agent (or hoard-agent.exe on Windows) — the binary
  • .env — a configuration file with your API key already filled in
Hoard Agent fetches its automation workflow from Hoard at startup and keeps it current on its own, so there’s nothing else to download or manage.

​
Configuration

Open the .env file. Both required values are already filled in:
HOARD_API_URL tells the agent which server to talk to. The generated .env includes it, and the agent defaults to https://www.tryhoard.com if it’s ever missing — only change it if you’re self-hosting.
Session preservation across restarts is on by default. When Hoard Agent restarts (auto-update, crash recovery, manual restart), it attaches to the live browser you logged into earlier instead of killing it and relaunching — so you don’t get bounced to the TCGplayer login page. The same behavior is controlled by the Preserve TCGplayer session across restarts checkbox in Hoard Desktop. Set HOARD_AGENT_ADOPT_CHROME=false to opt out.
Your .env file stays on your machine. Keep it private — it contains your Hoard API key. Hoard Agent does not store your TCGplayer password; you log into TCGplayer in the browser window.

​
First run

The first run opens a visible browser window so you can log into TCGplayer. This is needed because TCGplayer shows a CAPTCHA on login that Hoard can’t solve for you. After this one-time login, your session is saved and future syncs run in the background.
If macOS says the app “can’t be opened because it is from an unidentified developer,” the xattr command above fixes it. You can also go to System Settings > Privacy & Security and click Allow.
What happens:
  1. A Chrome window opens to TCGplayer’s login page
  2. Log in with your seller account, just like you normally would
  3. Complete the CAPTCHA if TCGplayer shows one
  4. Hoard Agent detects the login and starts syncing automatically
  5. Your session is saved locally so you won’t need to do this again until it expires

​
Running in the background

After the first login, run without HEADED=1:
Hoard Agent polls the Hoard server every 30 seconds, syncs when the server says it’s time (based on your sync schedule), and uses saved cookies from the first login. To keep it running after you close the terminal:
Create ~/Library/LaunchAgents/com.tryhoard.agent.plist:
Then load it:
If you’d rather skip all of this, Hoard Desktop handles auto-start for you on Mac and Windows. It’s the same binary, just with a wrapper that manages the lifecycle.

​
Session expiry

Like any website, TCGplayer sessions expire after a few days. When this happens:
  1. You’ll see “session expired” in the log output
  2. Run again with HEADED=1 — a browser window opens so you can log in
  3. Complete the CAPTCHA if TCGplayer shows one
  4. Done — back to background mode until the next expiry
In practice, sessions last anywhere from 3 to 7 days. Hoard Agent will keep trying to sync and logging “session expired” until you re-login, it won’t crash or lose data.
Headless Linux servers: If Hoard Agent runs on a server or a machine without a display, you’ll need a way to handle session re-login. A few options:
  • SSH with X forwarding. ssh -X yourserver then run HEADED=1 ./hoard-agent. The browser window appears on your local machine.
  • VNC or remote desktop. Connect to the server’s desktop, run Hoard Agent headed, log in, then disconnect. The session persists.
  • Hoard Desktop on a desktop machine. If re-login friction is a dealbreaker, run Hoard on a Mac or Windows machine where you can interact with the browser directly. Hoard doesn’t need much resources, any machine that stays on will do.
Hoard sends you an email if Hoard Agent has been offline for more than 24 hours, so you’ll know when a session expires even if you’re not watching the logs.

​
Sync schedule

Configure how often Hoard Agent syncs in Settings → Sync. How often you can sync depends on your plan: Hoard Agent must be running for syncs to happen. If it’s off during a scheduled sync, it picks up on the next poll. Settings > Sync also lets you pin a preferred local hour, set quiet hours, and choose allowed days of week. Those controls affect when the server tells Hoard Agent to run; you do not need to restart the agent after changing them.

​
What happens during a sync

Steps 2 and 3 repeat for each product line enabled in Settings. Inventory-detected games are pinned in Settings, and less common TCGplayer games can be added through search. Steps 4-8 are non-fatal. If orders or sales reports fail, the inventory sync still completes.

​
Cooldown after failures

If a sync fails on a critical step (login, export, or upload), Hoard Agent backs off and waits before retrying. The cooldown escalates: 5 minutes, then 10, then 30 (capped). This keeps it from hammering TCGplayer when something is genuinely wrong. You’ll see the cooldown status in your terminal.

​
Your data stays on your computer

​
Hoard Desktop vs Hoard Agent — switching later

If you started with Hoard Agent and want to switch to Hoard Desktop, just download the desktop app. It’ll detect your existing config at ~/.config/hoard/agent.env and pick up where you left off. Going the other way: if you have Hoard Desktop and want to switch to Hoard Agent, grab the standalone binary from the Hoard setup page (expand Advanced: manual agent setup (terminal)), copy your HOARD_API_KEY and HOARD_API_URL from ~/.config/hoard/agent.env into the .env file next to the binary, and run from your terminal.