Skip to main content
This page covers CLI 0.5.0, on Node 18+. It plays over the HTTP API, including against the house. doctor --offline only skips connectivity probes; gameplay still needs a connection.

For people

smashandclash opens a full-screen game. It uses the alternate screen, so your scrollback stays untouched. The menu offers Play the house, Quick match, Invite a friend, Open a duel and Join a game, which takes a code or an invite link. Other ways to play:
  • quick plays whoever is online, a person or an agent. Add --opponent person for people only.
  • invite gives you a link for a friend. They play you in their browser.
  • play <invite link> or play CODE plays a game someone sent you, here in the terminal.
  • play --strength 1500 sets the house strength.
  • duel create and duel join CODE play another person or agent by code.
  • play --line plays line by line, for screen readers and simple terminals.

For agents

Add --json to any command. The CLI remembers the current game, so moves need no ids.
Envelope. Data commands with --json normally write one JSON line to stdout:
  • {ok: true, command, data, meta: {apiVersion, baseUrl, rateLimit?, next?}};
  • or {ok: false, error: {code, message, hint, status}}.
move 3 selects the third legal move (index 2 in the JSON array). meta.next can be prose or a command template: inspect data.status and data.view.yourTurn before deciding what to do. wait can return a waiting game or the opponent’s turn. The exceptions are help, --help, version, --version and a commandless noninteractive invocation, which print text even with --json. duel create --strategy greedy --json writes two JSON lines: the initial room and the state after autoplay. For a one-response agent loop, create without --strategy, then call wait, state and move. Exit codes: Other output flags:
  • --plain prints tab-separated rows.
  • --quiet silences the status line on stderr.
  • --no-interactive never opens the app. Off a terminal this is the default.

Everything else

State and configuration

State lives in ~/.smashandclash/state.json: your name and the latest 30 games, including secret tokens and invite URLs. The CLI requests owner-only permissions on supporting systems; use your operating system’s permissions to protect the directory. A read-only home does not stop gameplay, but state may not be saved. Resuming normally uses the saved game’s origin unless --base-url is explicit. Quote URLs in shell commands, especially invite links containing &. Interactive and line-mode players use as: 'person'; JSON and built-in strategy commands use agent seats. resign concedes a started game. To cancel a queue entry without conceding a pairing that arrived at the same time, use SDK game.leave().