Skip to content

Graphical User Interface

Jump to bottom
tromador edited this page Jul 1, 2026 · 4 revisions

Contents

What The GUI Is

The GUI is a graphical front-end for the same Trade Dangerous engine used by the CLI.

In other words:

  • tradegui is the GUI front-end
  • trade is the command-line front-end
  • both use the same Trade Dangerous database and import pipeline
  • both work with the same current TD command set

This page is about how the GUI behaves and how to use it sensibly.

For installation and first-time setup, see the Setup Guide.

For the full command-line reference behind the GUI, see Command Line Options.

Starting The GUI

How you start the GUI depends on how you installed Trade Dangerous.

If you used the Windows installer

Start Trade Dangerous from the Start Menu.

If you chose the desktop shortcut during install, you can start it from there instead.

This is the packaged GUI install.

If you installed with pip

Start the GUI with:

tradegui

If you are running from source

Start the GUI with:

python tradegui.py

If you have not yet imported any market data, the GUI will still open, but most command workspaces will not have anything useful to work with until you import data.

Before You Start

The GUI uses the same TD data as the CLI. It does not come with a magically useful market database already loaded.

If you have not yet set TD up, go and read the Setup Guide first, then come back.

The short version is:

  1. install TD
  2. start the GUI
  3. use the Import workspace to bring in data
  4. then start using Run, Buy, Sell, Direct, and so on

How The GUI Is Laid Out

The GUI has three main areas.

Top Bar

At the top you will find:

  • a Command selector
  • a simple Status display
  • a toggle between Input, Results, and Diagnostics

Left Pane

The left pane holds your persistent baseline context:

  • Commander name
  • Credits
  • Max data age
  • Ship profile
  • Ship name
  • Capacity
  • Reserved capacity
  • Jump range full
  • Jump range empty

Think of this as your saved baseline rather than the details of one specific command.

Right Pane

The right pane holds the currently selected workspace.

For most commands, the right pane can show:

  • Input
  • Results
  • Diagnostics

The exceptions are:

  • Import, which uses the whole pane for import options, progress, and logging
  • Settings, which is GUI-only and does not execute a TD command

Commander Baseline And Ship Profiles

The left pane is where you tell the GUI about you and your current ship.

Commander Baseline

The commander baseline contains:

  • Commander name
  • Credits
  • Max data age (days)

These values are saved and reused between sessions.

They are also inherited by various command workspaces unless that workspace explicitly does something different.

Ship Profiles

Ship profiles let you keep more than one saved ship setup.

A ship profile contains:

  • Ship name
  • Capacity
  • Reserved capacity
  • Jump range full
  • Jump range empty

The GUI also shows Effective Capacity, which is simply the usable cargo space after reserved capacity has been taken off.

New, Save, Revert

The ship profile buttons work like this:

  • New creates a new ship profile based on the currently loaded one
  • Save permanently saves the current ship profile edits
  • Revert throws away unsaved profile edits and reloads the saved version

A small but important detail:

  • commander/global values save as you change them
  • ship profile edits affect the current session immediately, but are not permanently saved until you click Save

Autocomplete And Place Entry

Many of the GUI fields that deal with systems, stations, and common search terms now use autocomplete.

In practice that means the GUI will often help you choose a valid entry instead of making you type the whole thing exactly from memory.

This is most noticeable in fields such as:

  • From
  • To
  • Near
  • Via
  • Avoid
  • Buy search
  • Sell search

A few practical points are worth knowing:

  • system fields usually autocomplete on system names
  • station fields are shown separately where the GUI needs an explicit system/station pair
  • where a station depends on a chosen system, the station suggestions are scoped to that system
  • list-style fields such as Via and Avoid are stored as explicit GUI selections and then expanded back into the repeated CLI options TD expects

This is a GUI convenience layer. It does not change the underlying TD engine behaviour.

Workspaces

The command selector switches between the current supported GUI workspaces.

At time of writing, the supported workspaces are:

  • Run
  • Buy
  • Sell
  • Direct
  • Local
  • Market
  • Nav
  • Old Data
  • rare goods through Buy
  • Import
  • Settings

Run

CLI equivalent: trade run

This is the main trade run optimizer workspace, and it makes the heaviest use of the left pane.

In particular:

  • blank override fields inherit from the left pane
  • Copy from profile stamps the current left-pane values into run-local overrides
  • usable cargo is based on effective capacity, not just raw capacity

The main Run pane focuses on the common route-shaping inputs. Less common options live under Extended Options.

GUI-specific behaviour to note:

  • the left pane baseline is part of the execution context
  • command-local override fields win over the left pane
  • Copy from profile is a GUI convenience and has no direct CLI equivalent
  • the GUI uses the current saved/effective ship profile instead of making you type cargo and jump data every time
  • From and To use separate system and station inputs rather than a single raw CLI-style station string
  • Via is edited as a list of explicit system or system/station entries under Extended Options
  • Avoid is also edited under Extended Options, and may contain systems, system/station pairs, or item names
  • the GUI stores those Via and Avoid entries canonically and expands them into repeated CLI --via and --avoid options at execution time

For the underlying option meanings, see Command Line Options.

Buy

CLI equivalent: trade buy

The GUI keeps the main pane focused on the common inputs:

  • item/category search
  • near
  • distance
  • supply
  • common station filters

Less common constraints and sorting options live under Extended Options.

GUI-specific behaviour to note:

  • multiple search terms can be entered as comma-separated values
  • the main search field uses autocomplete to help with common valid search terms
  • Near uses system autocomplete
  • the left-pane Max data age is passed through as the CLI --age filter
  • the GUI field labelled Distance maps to CLI --ly
  • GUI Sort by units is the CLI --units-sort

For the underlying option meanings, see Command Line Options.

Sell

CLI equivalent: trade sell

This workspace is deliberately similar to Buy, but simpler.

GUI-specific behaviour to note:

  • the search field uses autocomplete
  • the GUI only uses the first search term for Sell
  • Near uses system autocomplete
  • the left-pane Max data age is passed through as CLI --age
  • the GUI field labelled Distance maps to CLI --ly-per, not --ly

That last point is worth knowing because Buy and Sell are not symmetrical in CLI naming even though the GUI tries to keep them feeling similar.

For the underlying option meanings, see Command Line Options.

Direct

CLI equivalent: trade direct <origin> <dest>

Use this when you already know the two endpoints you care about and just want the direct trade table.

GUI-specific behaviour to note:

  • the GUI always forces detail mode so it can render the richer trade table
  • GUI Cargo mode maps to the CLI cargo helpers:
    • Fill to capacity -> --fill
    • Load free space only -> --load
    • Full load from scratch -> --full-load
  • Reverse route is CLI --reverse

For the underlying option meanings, see Command Line Options.

Local

CLI equivalent: trade local

Typical uses include:

  • finding nearby trading systems
  • finding services such as shipyard, outfitting, repair, rearm, refuel
  • checking station traits and filters around a location

GUI-specific behaviour to note:

  • Near uses system autocomplete
  • the left-pane Max data age is inherited and passed to CLI --age
  • the GUI always forces detailed output so station/service results can be shown properly
  • the service checkboxes are GUI wrappers around the normal CLI service filters

For the underlying option meanings, see Command Line Options.

Market

CLI equivalent: trade market

You supply a station, and the GUI renders the market in a full-detail table view.

GUI-specific behaviour to note:

  • the GUI always forces higher detail so averages, ages, and related fields are available
  • GUI Buying only and Selling only map to the CLI --buying and --selling switches
  • this workspace is intended for inspection rather than route planning

For the underlying option meanings, see Command Line Options.

Nav

CLI equivalent: trade nav

This workspace calculates routes between places without worrying about trading profit.

GUI-specific behaviour to note:

  • the GUI always adds --stations and higher detail so stop-by-stop station results can be shown
  • Via and Avoid may be entered as comma-separated values or one-per-line
  • the GUI expands those into repeated CLI --via and --avoid options

For the underlying option meanings, see Command Line Options.

Old Data

CLI equivalent: trade olddata

This workspace helps you find stale market data that needs refreshing.

GUI-specific behaviour to note:

  • unlike many other workspaces, this does not use the left-pane Max data age
  • Near uses system autocomplete
  • Sort to shortest path is CLI --route
  • Limit and LS max are tucked away in Extended Options
  • Near is required if you want to use distance filtering or route sorting

For the underlying option meanings, see Command Line Options.

Rare goods

CLI equivalent: trade buy --rare

Rare goods are searched through the Buy workspace by enabling the rare filter.

GUI-specific behaviour to note:

  • Near uses system autocomplete
  • item/category fields can be left empty to list rare commodities found in live market data
  • ordinary Buy filters such as pad size, planetary state, fleet-carrier state, settlement state, data age, and price sorting still apply

For the underlying option meanings, see Command Line Options.

Import

CLI equivalent: trade import -P eddblink ...

This workspace handles the normal TD import/update workflow.

It is intentionally not a generic “all plugins” front-end. It is aimed at the supported, ordinary user workflow.

GUI-specific behaviour to note:

  • the import workspace is hard-wired to eddblink
  • it exposes the common eddblink options directly
  • import progress is shown live in the GUI
  • stopping an import is cooperative, not an instant hard kill

The most important practical point is this:

  • the import workspace always opens in the normal All + Skip Vendors mode
  • that is the sensible fuller refresh for most users
  • vendor tables take a very long time and are not needed by most people

So in GUI terms:

  • normal update: use the Import workspace in its normal default mode
  • heavier work: turn on the extra import options only when you actually mean it

For the underlying option meanings, see Plugin Options.

Settings

This is a GUI-only workspace.

It does not execute a TD command.

At time of writing it provides:

  • theme selection
  • advanced launcher-port settings

The available themes are:

  • Default
  • Elite Dark

The Advanced Settings dialog lets you set the local application port used when the GUI starts. Most users can ignore this completely.

Results And Diagnostics

Most workspaces can show three views:

  • Input
  • Results
  • Diagnostics

Results

Where possible, the GUI renders structured results rather than plain text.

For example:

  • Run shows routes, hops, and per-hop commodity tables
  • Direct, Buy, Sell, Local, Nav, Market, and Old Data are rendered as richer tables where possible

If a suitable structured renderer is not available, the GUI falls back to the normal TD text output.

Diagnostics

The Diagnostics view is where parser messages, warnings, and error output go.

If something fails, start there.

It is the GUI equivalent of asking “what did TD actually say?”

Saved State

The GUI remembers quite a lot between sessions.

It saves:

  • selected command
  • commander baseline
  • ship profiles
  • per-command drafts
  • theme/layout choices
  • launcher-port preference

This state is stored in a sidecar JSON file called:

tradegui_state.json

It lives in the TD data directory.

So:

  • the GUI remembers your working setup
  • but that GUI state file is separate from the actual TD market database

For packaged Windows installs, this will normally be under:

%LOCALAPPDATA%\TradeDangerous\data

For pip and source-based runs, it will normally be wherever your TD data directory lives unless you have explicitly set TD_DATA.

Persistent Drafts

The GUI persists almost everything you enter.

This includes commander defaults, ship profiles, and the drafts for the individual command work enter.

This includes commander defaults, ship profiles, and the drafts for the individual command workspaces. The intention is that once you have set TD up the way you like, you should not have to keep re-entering the same values every time you open the GUI.

The main exception is the Import workspace.

Unlike the other workspaces, Import does not try to remember every checkbox exactly as you last used it. It always opens in the normal All + Skip Vendors mode, and the heavier action-style options such as Clean, Optimize, and Force are cleared after use. This is intentional: those options are occasionally useful, but they are not the sort of thing most users should run repeatedly by accident.

A Sensible First Session

If you are opening the GUI for the first time, a sensible order is:

  1. start the GUI
  2. fill in your commander baseline
  3. fill in your ship details
  4. save the ship profile
  5. go to Import
  6. import data
  7. return to Run, Buy, Sell, Direct, or whatever you actually want to use
  8. use Results and Diagnostics to inspect what happened

If your main interest is the trade run optimizer, start with Run.

If you want to inspect or compare specific stations, Market and Direct are often quicker.

Troubleshooting

“The GUI opens but tells me there is no data”

You have not imported enough market data yet.

Use the Import workspace, or follow the import instructions in the Setup Guide.

“I changed ship values and they disappeared”

You edited the working ship profile but did not click Save.

Commander/global values save as you change them. Ship profiles do not.

“I stopped an import and now I don’t trust the results”

Good. Run the import again and let it finish.

A stopped import may leave the local data incomplete.

“The GUI remembers junk values”

Close TD and remove tradegui_state.json.

The GUI will recreate a fresh default state next time it starts.

“The CLI and GUI seem to be using different data”

They are probably being run from different folders, or with different data-directory settings.

Remember that TD stores its data relative to where it is run unless you centralise it with TD_DATA.

“Where should I look when something fails?”

Start with Diagnostics.

Home

Setup Guide

User Guide

Graphical User Interface

Command Line Options

Plugin Options

Cookbook

Temporary

Developers

Python Quick Peek

Prices (deprecated)

Clone this wiki locally