@theseam/cotton-trading

The Seam's cotton trading platform from a command line. Sign in with your Seam login, then read the offer book, your bids and purchases, invoices, drafts, recaps and market data in your terminal, or as JSON for your own scripts and spreadsheets.

npm install -g @theseam/cotton-trading
seam login
seam offers list --posted-today

Node.js 20 or later, on Windows, macOS or Linux. You need a login on The Seam at a company that has been given access to the trading API. Ask The Seam if you are not sure.

The full guide is seam docs, which opens it in your browser; seam docs --pdf saves a copy, and seam docs --md saves it as Markdown.

This package used to be called @theseam/trading-cli. If you installed it under that name, run npm uninstall -g @theseam/trading-cli first: both provide the seam command, so the new install otherwise stops with EEXIST. Your sign-ins are kept.

What you can do

| Group | For example | | --- | --- | | offers | the offer book, one offer, its recap, and the recap as a PDF | | bids | your bids, and the bids on one offer | | purchases, invoices, drafts | what you bought, what it cost, and the documents as PDFs | | market | trading hours and calendar, trading months, spot quotes and statistics | | warehouses, terms | warehouse details and tariffs, and trading terms | | seller-offers, seller-bids, seller-sales, seller-payments, seller-statements | the same, seen from the selling side | | analytics | totals and trends over your own trading |

seam list shows exactly what your login can use. Everything published today reads data; nothing changes it.

$ seam offers recap --offer-number 26083658
$ seam invoices document --invoice-id 209705          # saves invoice-209705.pdf
$ seam purchases list --all-pages --format csv --out purchases.csv

Signing in

seam login opens your browser on The Seam's sign-in page. Sign in with your usual Seam login and the two-step verification code The Seam sends you. Two-step verification is required: a login without it is refused, even where the website lets it in. Set it up on your profile's Two-Step Verification tab on The Seam's trading platform first. Your API key stays with The Seam: the command line holds only a sign-in token, which ends when you run seam logout, when access is withdrawn on the website, or after 30 days without use.

If the browser doesn't open by itself, run seam login --no-browser and open the address it prints in a browser on the same computer: the sign-in finishes by returning to seam there. On a server with no browser at all, such as one you reach over SSH, use an API key instead (see Scripts below).

More than one sign-in

To switch between logins, such as an admin checking what a buyer sees, give each sign-in a name. Each one stays signed in, so switching needs no browser and no new code:

seam login --as admin           # sign in as the admin
seam login --as buyer           # and, separately, as the buyer
seam offers list --as buyer     # one command as the buyer
seam use buyer                  # buyer from now on, until you choose another
seam accounts                   # the sign-ins kept here, and which is in use
seam logout --as buyer          # sign out of just that one

SEAM_ACCOUNT=buyer picks one for a whole terminal window. --as beats SEAM_ACCOUNT, which beats seam use. A sign-in without a name is called default, and it's the one used when nothing else is chosen. Each platform has its own sign-ins, so seam use on test doesn't change prod. Naming an account with --as or SEAM_ACCOUNT also sets aside any SEAM_API_KEY, so a key you keep for scripts can't answer in place of a sign-in you asked for.

Commands

Every command is a group and a command in it, with options in lowercase dashed words:

seam list                                       # everything available to you
seam offers                                     # the commands in one group
seam offers list --posted-today --limit 5
seam offers recap --offer-number 26083658       # laid out like the recap document
seam invoices document --invoice-id 209705      # saved as a PDF, never overwriting
seam offers list --help                         # what a command does and takes
seam whoami                                     # your role and permissions

• An option on its own means yes: --posted-today is --posted-today true.
• Options are checked before anything is sent, and a mistake gets a message saying what the command does take.
• Answers are written for reading: tables that fit your terminal, labeled fields, and recaps laid out like the document. --format json prints JSON instead, and --format csv prints CSV for a spreadsheet. --json and --csv, the earlier spelling, still work for now and print a reminder of the new one.
• --all-pages follows a list through up to 20 pages.
• Anything that changes data needs --yes.
• seam call offers_list --postedToday, the older spelling, still works.

Exit codes are 0 for success, 1 when The Seam refused or failed, or you aren't signed in, and 2 when the command was wrong and nothing was sent.

Scripts and scheduled jobs

A job that can't open a browser uses an API key issued on The Seam's website under Trading → API Keys:

export SEAM_API_KEY=...        # never --key: a key on a command line ends up in shell history
seam offers list --updated-since 2026-10-13T08:00:00 --format json

With SEAM_API_KEY set, the CLI calls the API directly and doesn't need a sign-in. Commands and options are the same either way.

The key wins over your sign-in unless you name a sign-in with --as or SEAM_ACCOUNT. If you keep a key in your user environment, seam whoami and seam login say so, because otherwise every command answers as the key rather than as you.

Choosing columns and formats

Which columns each list shows, in what order, and how answers print when you don't give --format, are kept in ~/.seam/config.json, on your computer only. The Seam keeps no copy.

$ seam config edit --web       # a settings page on the trading site; saving writes the file here
$ seam config edit             # the file in $VISUAL, $EDITOR or Notepad
$ seam config columns          # the commands whose columns can be chosen, and their columns
$ seam config                  # what the file says
$ seam config reset --yes      # delete it: back to the defaults

{
  "format": "text",
  "outputs": {
    "offers list": { "columns": ["Offer", "Bales", "Price", "Est Basis"] },
    "purchases list": { "format": "csv" }
  }
}

The command line beats the file and the file beats the defaults: --format for one command, and --columns "Offer,Bales,Price" for one table. A mistake in the file stops commands with a message naming the file and the entry, before anything is sent.

Settings

| Variable | Flag | Default | | --- | --- | --- | | SEAM_ENV | --env | test until trading.theseam.com is live, then prod | | SEAM_MCP_URL | --server | the platform's trading server | | SEAM_API_URL | --api-url | the platform's API (key mode only) | | SEAM_API_KEY | | unset: use your sign-in | | SEAM_ACCOUNT | --as | the account chosen with seam use, else default | | SEAM_CONFIG_DIR | | ~/.seam, where sign-in tokens and your settings file are kept |

--env picks a platform, and each platform names both addresses:

| --env | Trading server | API | | --- | --- | --- | | prod | https://trading.theseam.com/mcp | https://api.theseam.com | | test | https://testtrading.theseam.com/mcp | https://testapi.theseam.com |

A key works only on the platform that issued it, so switching both together saves a key being sent where it means nothing. You stay signed in to each platform separately. --server and --api-url are for anything else, such as a server on your own machine, and win over --env; --env wins over the address variables, so --env prod works for one command even with SEAM_MCP_URL set in your profile. seam whoami and the --yes refusal say which platform you are on.