tossinvest-cli: Toss Securities from the Terminal and from AI Agents

The gap tossinvest-cli fills for Toss Securities users

Toss Securities offers an official Open API, and a retail investor who wants to automate against it has to write the client, handle auth, and accept that a large part of what the Toss web app shows is simply not in that API. Supply and demand data, market indices, AI signals, condition-based screeners, watchlist management, a transaction ledger, real-time push and fractional won-denominated orders are described in the README as WTS-only features. The project's claim is that it covers 100% of the official Open API range and adds 39 such web-app features on top.

The audience is narrow and specific. This is for someone who already holds a Toss Securities account, is comfortable in a terminal or inside an AI coding agent, and wants structured output rather than a browser tab. The README positions the same binary, tossctl, for both Claude Code, Codex, Gemini, Cursor and GitHub Copilot through an MCP server, and for plain scripts and automation through the CLI. JSON and CSV output are treated as first-class, which is what makes the agent path workable at all.

The project is written in Go and released under MIT. It is not an official Toss product, and the README states that plainly in a warning block.

How the hybrid routing between the official API and internal endpoints works

The README describes a hybrid model rather than a single protocol. If you connect an official Open API key, the features that Toss officially supports run through that supported path. Everything else, the web-app-only surface, is reached through Toss's internal web APIs.

That split is the central design decision, and it is also the source of most of the risk. The README warns that internal APIs can change without notice, and that using them may violate the Toss Securities terms of service. It also states that the developer accepts no liability for account restrictions, losses or other consequences. You should read that as a factual description of the architecture, not as marketing hedging: one half of the tool sits on a supported contract, the other half sits on an interface that was not published for third parties.

Authentication is browser-based rather than key-based for the default flow. The install script sets up Google Chrome and Python, which auth login needs. You scan a QR code, and then you must also confirm the "keep this device logged in" prompt that appears on your phone. The README is explicit that skipping that second confirmation leaves the session expiring after roughly one hour idle. You can verify what you actually got with tossctl auth status, which should report a persistent cookie with an expiry.

For machines without a GUI, auth login --headless prints the QR URL and an answer letter to stderr, so you can open the URL on a phone and approve without a camera. The QR file written by --qr-output is stored with 0600 permissions.

Installing tossctl and running a first read-only query

The install script is the shortest path on macOS and Linux. It downloads and installs the binary; the README notes that auth login additionally needs Google Chrome and Python, which the script configures.

curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh

On Windows the equivalent is a PowerShell one-liner, and the README also points to GitHub Releases and Homebrew as alternatives.

irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex

After installing, verify the setup before touching anything account-related. tossctl doctor checks the environment, and tossctl auth login starts the browser flow.

tossctl version
tossctl doctor
tossctl auth login

Then run a read-only command and ask for JSON. The README uses account summary as the first example, and the JSON output is what an agent or a script would consume.

tossctl account summary --output json

If you are wiring this into an agent instead of a shell, register the MCP server once and let the agent call the tools. The README gives this exact command for Claude.

claude mcp add tossctl tossctl mcp

Upgrades go through tossctl update. If you installed via Homebrew, the README says that command delegates to brew upgrade tossctl-cli.

Trading is disabled by design, and that shapes every workflow

The README states that all trading functionality is turned off immediately after installation. Nothing executes until you explicitly enable it per feature in config.json. That is a sensible default for a tool that an AI agent can drive, and it means the first hour with tossinvest-cli is entirely read-only unless you go out of your way.

The README's own agent instructions reinforce the same discipline: use read-only commands first, and always run tossctl order preview before any trading mutation. The preview is a dry-run of the order, which is the only cheap way to catch a wrong ticker or a wrong quantity before it becomes a filled trade.

This is a genuine limitation as much as a safety feature. Anyone expecting to install the CLI and place an order in the same minute will be editing configuration first. The project has decided that the friction is worth it, and given that the client can be attached to an autonomous agent, that judgement is defensible. It does mean that any automation you build has to treat "trading disabled" as a state it may encounter at runtime, not just at setup.

Session expiry is the operational cost nobody can remove

Toss runs a roughly seven-day active expiry clock separately from the SESSION cookie, which carries a one-year Max-Age. The README is unusually clear about this: from 24 hours before expiry, every command prints a warning to stderr telling you to run tossctl auth extend.

Extending sends a push to the Toss app on your phone and waits for approval, with a default timeout of 120 seconds that you can shorten with --timeout. This is Toss's second factor and the README says it cannot be removed. What can be automated is when the request is made. The --if-expiring flag checks the server first and exits 0 without doing anything if there is more headroom than the window you specify.

tossctl auth extend --if-expiring 48h

The README shows a macOS launchd example that runs this daily at 09:00. The practical consequence is that unattended automation on this tool will eventually stop and wait for a human with a phone. If your workflow assumes a long-lived credential with no interactive step, tossinvest-cli is the wrong tool, regardless of how good the CLI surface is.

Where the official Open API is the better choice

The honest alternative is Toss Securities' own official Open API, used directly. The difference is not feature count, it is the contract. The official API is a supported interface: Toss documents it, Toss maintains it, and using it does not raise the terms-of-service question that the README itself flags for the internal endpoints.

What you give up by going official is the web-app-only surface. Supply and demand, AI signals, condition screeners and watchlist writes are exactly the things the README lists as WTS-only, and they are the reason someone would pick tossinvest-cli over a thin client against the official API. If your use case is quotes, balances and standard order placement, the official API covers it and you avoid the entire class of breakage that comes from depending on internal endpoints that can change without notice.

A second alternative is simply not automating at all. For an investor who checks a portfolio a few times a week, the Toss app already does this, and the login ceremony described above is pure overhead. The tool earns its place when the access pattern is programmatic and repeated.

Maintenance, licensing and what the repository tells you

The repository is not archived, and the last push was on 2026-08-25, the same day as the v0.43.1 release. The release cadence visible in the release list is tight: v0.42.0 and v0.43.0 both landed on 2026-08-24, with v0.43.1 the following day. That pattern suggests the project is being iterated on actively, but it also means the surface can move. Pin a version if you build automation on top of it.

The licence is MIT, which permits commercial and private use with the usual warranty disclaimer. That licence covers the code in this repository. It does not cover your relationship with Toss Securities, and it does not change the terms-of-service question the README raises about the internal API path. The MIT grant and the broker's terms are separate documents governing separate things; if the internal-API path is load-bearing for your use case, that is a question for your own reading of the Toss terms, not something the repository's licence answers.

Upgrade cost is low by design. tossctl update handles the binary, and Homebrew installs delegate to brew upgrade tossctl-cli. The Makefile shows a build path with go build against ./cmd/tossctl and a lint target that is gofmt plus go vet with no extra tooling, so building from source does not drag in a toolchain beyond Go 1.25.13 and the modules in go.mod.

Editorial conclusion

Adopt tossinvest-cli if you already trade through Toss Securities and want scripted or agent-driven access to quotes, portfolio and web-app-only data such as supply/demand and screeners, and you accept that most of those calls go through internal APIs. Do not adopt it if you need a vendor-supported, contractually safe integration path, or if you cannot tolerate a login that expires and requires phone approval roughly weekly. Before trusting it with anything, run tossctl doctor, complete tossctl auth login, and confirm the trading switches in config.json are still off.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes