Documentation Index
Fetch the complete documentation index at: https://docs.tryhoard.com/llms.txt
Use this file to discover all available pages before exploring further.
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 (Standard, Pro, or Reserve) with API key
If Chrome isn’t installed, Hoard Agent downloads a compatible Chromium automatically on first run (~200MB, one time).
Download
Download Hoard Agent from GitHub Releases or from the Hoard setup page (expand “Advanced: manual setup”).
Each download includes:
hoard-agent (or hoard-agent.exe on Windows) — the binaryworkflows/tcgplayer.yaml — the automation workflow.env — configuration file (fill in your values)
Configuration
Open the .env file and fill in your values:
# Required — get this from Settings at tryhoard.com
HOARD_API_KEY=your-api-key-from-dashboard
# Optional
# HEADED=1 # Show browser window (useful for debugging)
# DEBUG=1 # Verbose logging + failure screenshots
# HOARD_AGENT_ADOPT_CHROME=true # Beta: preserve TCGplayer session across agent restarts
HOARD_AGENT_ADOPT_CHROME=true is the CLI equivalent of the Preserve TCGplayer session across restarts (beta) checkbox in Hoard Desktop. When set, Hoard Agent attaches to a live Chrome left over from a prior run instead of killing it and relaunching — so auto-updates and crash recovery don’t bounce you to the TCGplayer login page. Defaults off while the feature is in beta.
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.
# Remove the macOS quarantine flag (one time, same as any app from the internet)
xattr -d com.apple.quarantine hoard-agent
# First run — opens a browser so you can log into TCGplayer
HEADED=1 ./hoard-agent workflows/tcgplayer.yaml
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.
set HEADED=1
hoard-agent.exe workflows\tcgplayer.yaml
Windows SmartScreen may show “Windows protected your PC.” Click More info, then Run anyway. This only happens on first launch.
chmod +x hoard-agent
HEADED=1 ./hoard-agent workflows/tcgplayer.yaml
- A Chrome window opens to TCGplayer’s login page
- Log in with your seller account, just like you normally would
- Complete the CAPTCHA if TCGplayer shows one
- Hoard Agent detects the login and starts syncing automatically
- 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 workflows/tcgplayer.yaml
Mac (launchd)
Linux (systemd)
Windows (Task Scheduler)
Create ~/Library/LaunchAgents/com.tryhoard.agent.plist:<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.tryhoard.agent</string>
<key>ProgramArguments</key>
<array>
<string>/path/to/hoard-agent</string>
<string>/path/to/workflows/tcgplayer.yaml</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>HOARD_API_KEY</key>
<string>your-api-key</string>
</dict>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
</dict>
</plist>
launchctl load ~/Library/LaunchAgents/com.tryhoard.agent.plist
Create ~/.config/systemd/user/hoard-agent.service:[Unit]
Description=Hoard Sync Agent
[Service]
ExecStart=/path/to/hoard-agent /path/to/workflows/tcgplayer.yaml
Environment=HOARD_API_KEY=your-api-key
Restart=always
RestartSec=30
[Install]
WantedBy=default.target
systemctl --user enable hoard-agent
systemctl --user start hoard-agent
Open Task Scheduler and create a new task:
- Trigger: At log on
- Action: Start a program
- Program:
C:\path\to\hoard-agent.exe
- Arguments:
workflows\tcgplayer.yaml
- Start in:
C:\path\to\ (the folder containing the binary)
Add the HOARD_API_KEY environment variable to your system or user environment. 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:
- You’ll see “session expired” in the log output
- Run again with
HEADED=1 — a browser window opens so you can log in
- Complete the CAPTCHA if TCGplayer shows one
- 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 workflows/tcgplayer.yaml. 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 Hoard Settings:
| Schedule | Best for |
|---|
| Every 4 hours | Most sellers (default) |
| Every 8 hours | Moderate-volume stores |
| Every 12 hours | Lower-volume stores |
| Once daily (24 hours) | Low-volume or testing |
What happens during a sync
1. Login check — verify TCGplayer session is valid
2. Export inventory — for each product line, download your pricing CSV
3. Upload to Hoard — for each product line, send inventory data to the server
4. Export orders — download recent order history
5. Upload orders — send order data to the server
6. Sales reports — download and upload financial data
7. Price updates — download repricing CSV from Hoard
8. Import prices — upload new prices to TCGplayer
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
| What | Where | Sent to Hoard? |
|---|
| TCGplayer session cookies | Stored locally on your computer | Never |
| Hoard API key | Your .env file | Yes (to authenticate syncs) |
| Inventory & order data | Exported from TCGplayer by Hoard Agent | Yes (this is what powers your dashboard) |
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 GitHub Releases, copy your API key from ~/.config/hoard/agent.env into the .env file, and run from your terminal.
