Skip to content
Alpha version. These pages describe a game that is not built yet. Everything here can still change, and in the alpha every city can be reset at any time.

The CLI ​

The CLI is a tool for your terminal. It is called delivery. It is the same tool for every player, whatever language your program is in, and also if you write no program at all.

It does two jobs:

  1. It controls your company in a live city, from outside.
  2. It runs a city on your own machine, so you can test your program before you push it.

On this page, a call is one line that you type. The word command is kept for a command of the game, which changes the city.

Installing and signing in ​

  1. Download the one program for your kind of machine. For controlling your company from outside, nothing else is needed. For a local run you also need Python or Go on your machine, because your own program runs there.
  2. Create an access key on the game's website, on the Connect screen.
  3. Give it to the CLI:
$ delivery login
Access key: ********
Signed in as anna-k.

There is one kind of access key. With it the CLI can read everything you can see and do everything you can do.

$ delivery use riverton
Now working in the city "riverton".

Every call can also name another city with --city.

Looking around ​

$ delivery status
Riverton · day 14, tick 3 402
Company   Red Line            rank 2 of 5
Wealth    18 250              cash 12 480 · cars 6 100 · loan 330
Cars      3                   2 driving · 1 at Fuel station
Code      version 31, running · 0 errors
You typeWhat it does
delivery citiesYour cities, and the listed shared cities, each marked as a lobby or as running.
delivery statusYour company at a glance.
delivery show ordersRead data. In place of orders you can name anything a program can read: cars, map, markets, businesses, companies, me.
delivery changes --since 3400The events and the changed data since a tick. With --follow it keeps asking and prints what comes.
delivery decisionsYour history of decisions. You can filter by car, by business, by who decided and by result.

Sending commands ​

There is one call for every command of the game, with the same name.

$ delivery car 2 go-to storage-north --reason "trying a route by hand"
accepted
$ delivery car 2 load order-881
refused: too_heavy

Every call that sends a command takes --reason "text". Give one. It shows up in your history of decisions.

The CLI is not sent events. Your uploaded program is told when a car is free. The CLI has to ask, with delivery changes.

Your uploaded program ​

You typeWhat it does
delivery code statusWhich version runs, the state of your last push, recent errors.
delivery code restartRestart your program.
delivery code logRead what your program logged. With --follow it keeps printing.
delivery code check main.pyAsk the game whether this code would be accepted, without pushing it.
delivery action listThe actions your program offers.
delivery action call set_highest_bid 6000Call one of them, and see the answer.
delivery memory list, get, set, delRead and change your program's memory.

Local runs ​

A local run is a city on your own machine. Nothing in it is real, and you can try anything.

$ delivery run main.py --new
Local run · a new city · seed 4711 · rules version 12
tick 0     car 1 is free (started)
tick 0     car 1: go_to storage-2   "order 3 pays 14"
...

The rules in a local run are exactly the rules of the game. The CLI downloads them from the game, in the version your city uses.

A local run waits for your program. The next tick starts only when your program has answered. So a local run gives the same result every time, and you can stop your program on any line for as long as you like.

Where a local run starts ​

You typeWhere it starts
--newA new city. You can give --seed and the settings.
--from rivertonYour live city as it is right now.
--from riverton --at 3380A moment of your city's past.

A run from a solo city goes on exactly as that city would.

A run from a shared city is different. You get the public data of the city and your own private data, and nothing private of anyone else. So the rest of the city is played back: the orders, the offers and the other companies' cars do what they did, and only your company is run by your program. It is not exact, because the others do not react to what you do differently. But it puts your program into a real situation.

Testing against another program ​

$ delivery run main.py --with old_version.py --with careful.py --new

This starts a local city with three companies, each run by its own program. It is the plain way to see how your program does against other programs, for example against your own older version.

Three promises ​

  • A run that cannot get its starting point stops. It never quietly uses another city.
  • Every run says which city and which moment it used, at the start and in its summary.
  • The CLI has no rules of its own about which code is accepted. It asks the game.

For your own programs ​

A program can use the CLI too.

  • Every call can answer as data. Add --json, and the answer has a fixed form that a program can read.
  • The way a call ends says what happened. Each of these ends with its own number: the call worked; the game refused it; you are not allowed to do it; the server could not be reached; in a local run, your program crashed; the starting point could not be had. "I could not find out" never looks like "it worked".

A program in Python or Go does not have to go through the CLI. It can use the game's library directly, see Writing code.

Delivery is part of simgit.io. This is an alpha version.