Usage¶
TLDR¶
Edit the config.yaml and items.csv files in the bin folder.
From the bin folder, run any of the following commands:
Important
Run the ffxiahbot command inside a directory that contains a config.yaml and optionally an items.csv.
Warning
The way you run the ffxiahbot command depends on how you installed it.
| Installation Method | Command |
|---|---|
| uv | uv run ffxiahbot --help |
| pipx | ffxiahbot --help |
Creating the Config File¶
You must create a YAML file to configure the tool (config.yaml). All other
options are passed as command line arguments.
# ah
name: M.H.M.U. # Name that appears on AH when buying and selling
tick: 30 # seconds between buying
restock: 3600 # seconds between selling
use_buying_rates: false # Only buy items a fraction of the time?
use_selling_rates: false # Only sell items a fraction of the time?
# sql
hostname: 127.0.0.1 # SQL parameter
database: xidb # SQL parameter
username: root # SQL parameter
password: root # SQL parameter
port: 3306 # SQL parameter
fail: true # fail on SQL database errors?
Running the CLI¶
Simply run the ffxiahbot from the command line. Specify the app you want to
run and any flags you want to set.
Warning
Common command line flags like --verbose must come before the name of the app to run. App specific command line flags must come after the name of the app to run.
➜ uv run python -m ffxiahbot --help
Usage: python -m ffxiahbot [OPTIONS] COMMAND [ARGS]...
The script will interact with the Auction House of a private Final Fantasy XI
server.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --version Show version string. │
│ --silent Only show ERROR messages. │
│ --verbose Also show DEBUG messages. │
│ --logfile PATH The path to the log file. │
│ [default: ahbot.log] │
│ --disable-logfile Disable logging to a file. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ broker Run a bot that buys and sells items on the auction house │
│ continuously. │
│ clear Delete items from the auction house (dangerous operation!). │
│ refill Refill the auction house with the items defined in the CSV file. │
│ scrub Download a list of item prices from ffxiah.com and save to a CSV │
│ file. │
╰──────────────────────────────────────────────────────────────────────────────╯
Note
You do not actually need a live or production SQL database to test these commands.
- Instead, you can pass the
--use-sqlite-dbflag to use a fake SQLite database instead. - This will manipulate a SQLite database file on your machine instead of a real server's database.
- You can then inspect the database with any tool that can read SQLite databases.
Downloading a new Items CSV¶
This command will download item data from ffxiah.com and save it to a CSV file.
➜ uv run ffxiahbot --verbose scrub
➜ uv run ffxiahbot --verbose scrub --server ASURA
➜ uv run ffxiahbot --verbose scrub --item-id 1 --item-id 2 --item-id 3
➜ uv run ffxiahbot --verbose scrub --cat-url http://www.ffxiah.com/browse/62/grips
Important
There is a pre-built CSV file in the repo, so you do not need to run this command if you don't want to.
Note
Pass the --cache .cache flag to the scrub app to save intermediate data during the scrubbing process.
This will allow you to resume the scrubbing process if it is interrupted.
Delete the .cache folder to start the scrubbing process from scratch.
Note
Set FFXIAHBOT_SCRUB_MAX_FAILURES=N to the number of failures (N) you are willing to accept before the scrubber stops.
Note
Enable the asyncio logger by setting FFXIAHBOT_SCRUB_DEBUG_ASYNCIO=1
➜ uv run python -m ffxiahbot scrub --help
Usage: python -m ffxiahbot scrub [OPTIONS]
Download a list of item prices from ffxiah.com and save to a CSV file.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config PATH Config file path. [default: config.yaml] │
│ --out-csv PATH The output CSV file to save. │
│ [default: items.csv] │
│ --server SERVER The server name (asura, bahamut, etc). │
│ [default: ASURA] │
│ --cat-url TEXT Preset category URLs. [default: None] │
│ --item-id INTEGER Preset item IDs. [default: None] │
│ --overwrite Overwrite output CSV? │
│ --stock-single INTEGER The default number of items for singles. │
│ [default: 10] │
│ --stock-stacks INTEGER The default number of items for stacks. │
│ [default: 10] │
│ --backup Backup output CSV? │
│ --cache PATH A directory to cache the fetched data │
│ [default: None] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
Refilling the Auction House¶
Important
Run the refill app to populate the AH if you want to buy items immediately!
➜ uv run python -m ffxiahbot refill --help
Usage: python -m ffxiahbot refill [OPTIONS]
Refill the auction house with the items defined in the CSV file.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config PATH Config file path. [default: config.yaml] │
│ --inp-csv PATH Input CSV file path. [default: (items.csv)] │
│ --no-prompt Do not ask for confirmation. │
│ --use-sqlite-db PATH Use a test SQLite database instead of the real │
│ one? │
│ [default: None] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
Clearing the Auction House¶
This command will remove all items for sale from the AH.
Warning
This command is pretty destructive, so be careful!
Important
Unless --all is specified, this command will only clear items that are for sale by the bot.
➜ uv run python -m ffxiahbot clear --help
Usage: python -m ffxiahbot clear [OPTIONS]
Delete items from the auction house (dangerous operation!).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config PATH Config file path. [default: config.yaml] │
│ --no-prompt Do not ask for confirmation. │
│ --all Clear all items. │
│ --use-sqlite-db PATH Use a test SQLite database instead of the real │
│ one? │
│ [default: None] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
Running the AH Broker Bot¶
Warning
The broker will wait until the 1st cycle defined in your config before populating items.
➜ uv run python -m ffxiahbot broker --help
Usage: python -m ffxiahbot broker [OPTIONS]
Run a bot that buys and sells items on the auction house continuously.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config PATH Config file path. │
│ [default: config.yaml] │
│ --inp-csv PATH Input CSV file path. │
│ [default: (items.csv)] │
│ --buy-items --no-buy-items Enable the buying of │
│ items. │
│ [default: buy-items] │
│ --sell-items --no-sell-items Enable the selling of │
│ items. │
│ [default: sell-items] │
│ --buy-immediately Buy items immediately │
│ instead of waiting? │
│ --restock-immediately Restock items immediately │
│ instead of waiting? │
│ --use-sqlite-db PATH Use a test SQLite database │
│ instead of the real one? │
│ [default: None] │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
Manually Editing the Items CSV¶
- Item data is stored in items.csv (you can edit it with a text editor or Excel)
- There is an already generated items.csv in the bin folder for you
Warning
- There is no reason to run the scrub app as an
items.csvis included already in the repository! - You do not need to regenerate the database even if you think it is old!
- You can cause yourself pricing issues, you have been warned!
Warning
Retail sometimes has unexpected prices in the history.
- There may be ancient entries.
- An item may have a selling price below an NPC buying price.
- An item may only really sell as either a stack or a single.
This may result in exploits on your server if you are not careful.
| column | description | value | note |
|---|---|---|---|
| itemid | unique item id | integer >=0 | |
| name | item name | string | |
| sell_single | sell single? | 0=false 1=true | |
| buy_single | buy single? | 0=false 1=true | |
| price_single | price for single | integer >=1 | |
| stock_single | restock count (single) | integer >=0 | |
| sell_rate_single | sell rate (single) | float 0 <= x <= 1 | disabled unless use_selling_rates=true |
| buy_rate_single | buy rate (single) | float 0 <= x <= 1 | disabled unless use_buying_rates=true |
| sell_stacks | sell stack? | 0=false 1=true | |
| buy_stacks | buy stack? | 0=false 1=true | |
| price_stacks | price for stack | integer >=1 | |
| stock_stacks | restock count (stack) | integer >=0 | |
| sell_rate_stacks | sell rate (stack) | float 0 <= x <= 1 | disabled unless use_selling_rates=true |
| buy_rate_stacks | buy rate (stack) | float 0 <= x <= 1 | disabled unless use_buying_rates=true |