Commands¶

pb¶

pb COMMAND [OPTIONS]

Talk to Pybricks hubs.

A hub stays connected between commands, so you only need to run pb connect once.

Hubs:

connect: Connect to a hub and keep it connected.
disconnect: Disconnect a hub.
status: Show what a hub is doing.
list: List the hubs that are currently connected.
use: Choose the hub that commands act on when none is named.
scan: Look for Pybricks hubs that are switched on and in range.

Programs:

run: Compile a script, send it to a hub, and run it.
repl: Talk to a hub's interpreter, a line at a time.
download: Compile a script and send it to a hub without running it.
start: Start a program that is already on the hub.
stop: Stop the program running on a hub.
check: Check that a program compiles, without sending it anywhere.

Background service:

service: Manage the background service that keeps hubs connected.

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]
--help, -h: Display this message and exit.
--version: Display application version.

pb connect¶

pb connect [OPTIONS]

Connect to a hub and keep it connected.

The connection outlives this command, so later commands reuse it rather than reconnecting.

Parameters:

--hub: The hub's name, as shown by pb scan. Defaults to the first hub found. [env: PB_HUB]
--scan, --no-scan, -s: Watch for hubs and choose one from the list. There is no time limit, so the hub can be switched on whenever you like, and Ctrl-C gives up without connecting to anything. [env: PB_S] [default: False]
--transport: Reach the hub this way: usb, ble or rfcomm. By default whichever works, preferring USB where a hub is reachable more than one way. [env: PB_TRANSPORT]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb disconnect¶

pb disconnect [OPTIONS]

Disconnect a hub.

Parameters:

--hub: Which hub, by name. Defaults to the one in use. [env: PB_HUB]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb status¶

pb status [OPTIONS]

Show what a hub is doing.

Parameters:

--hub: Which hub, by name. Defaults to the one in use. [env: PB_HUB]
--full, --no-full: Show every detail, including the ones that only mean something when you are debugging. [env: PB_FULL] [default: False]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb list¶

pb list [OPTIONS]

List the hubs that are currently connected.

Parameters:

--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb use¶

pb use [OPTIONS]

Choose the hub that commands act on when none is named.

With no options, this lists the hubs that are connected and the hubs it can hear, and lets you choose one with the arrow keys.

What is remembered is the hub's name, so the choice survives the hub being switched off and on, and outlives the background service. Every shell sees the same choice.

Parameters:

--hub: The hub's name. It does not have to be connected, or even switched on, so the hub a project belongs to can be chosen before any of it is plugged in. [env: PB_HUB]
--clear, --no-clear: Forget the chosen hub. Commands then act on whichever hub is connected, as long as there is only one. [env: PB_CLEAR] [default: False]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb scan¶

pb scan [OPTIONS]

Look for Pybricks hubs that are switched on and in range.

Nothing is connected to, which is the point: this answers "is it on, and can I hear it?" without taking the hub away from whatever else might want it.

Parameters:

--timeout: How long to scan, in seconds. [env: PB_TIMEOUT] [default: 10.0]
--name: Only show hubs with this name. [env: PB_NAME]
--transport: Only look on this transport: usb, ble or rfcomm. All of them by default. [env: PB_TRANSPORT]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb run¶

pb run [OPTIONS] [ARGS]

Compile a script, send it to a hub, and run it.

The command stays with the program: its output appears as it is printed, and on a terminal the keyboard goes to the hub, so Ctrl-C interrupts and input() reads what you type. Press Escape twice to stop the program; Ctrl-] q leaves, and Ctrl-] h lists the rest. Without a terminal -- in a pipeline or a build -- the output still comes through, on stdout.

Arguments:

SCRIPT: The Python file to run. Leave it out when using --command. [env: PB_SCRIPT]

Parameters:

--command, -c: Python code to run, instead of a file. Like python -c. [env: PB_C]
--hub: Which hub, by name. Defaults to the one in use. [env: PB_HUB]
--slot: Which program slot to use. [env: PB_SLOT]
--wait, --no-wait: How long to stay with the program, and how much of the terminal to use while doing it. Left out, the session takes the terminal when there is one. --wait stays but leaves the terminal alone and only prints the output, which is what a script wants. --no-wait starts the program and returns, for setting a robot going and walking away. [env: PB_WAIT]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb repl¶

pb repl [OPTIONS]

Talk to a hub's interpreter, a line at a time.

Everything typed goes to the hub, Ctrl-C included -- which is how a running program is interrupted. The one key that does not is Ctrl-], which introduces a command for pb itself: Ctrl-] q leaves, and Ctrl-] h lists the rest.

Escape pressed twice stops whatever the hub is running. Here that is the interpreter, so it ends the session as well; Ctrl-C is the lighter one for interrupting a line that is taking too long.

Ctrl-D ends the interpreter, and so ends the session. A hub already busy with a program of its own is left alone rather than interrupted.

A status line along the bottom says which hub is being talked to, whether anything is listening, and whether its battery is about to end the conversation.

Parameters:

--hub: Which hub, by name. Defaults to the one in use. [env: PB_HUB]
--replay: How much earlier output to show first, in bytes. Useful for joining a program that is already running and printing. [env: PB_REPLAY] [default: 0]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb download¶

pb download [OPTIONS] SCRIPT

Compile a script and send it to a hub without running it.

A program goes into whichever slot the hub has selected -- the hub decides, and its buttons are what change the selection. Naming a slot here says which one you expect, and the download is refused rather than put somewhere else if the hub disagrees.

Arguments:

SCRIPT: The Python file to send. [required] [env: PB_SCRIPT]

Parameters:

--hub: Which hub, by name. Defaults to the one in use. [env: PB_HUB]
--slot: The slot it should land in. Defaults to whichever the hub has selected. [env: PB_SLOT]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb start¶

pb start [OPTIONS]

Start a program that is already on the hub.

Nothing is sent to the hub, so this is the quick way to run the same program again, and the way to run one put there by another tool. What happens after it starts is exactly what happens for pb run.

Parameters:

--hub: Which hub, by name. Defaults to the one in use. [env: PB_HUB]
--slot: Which program slot. Defaults to the one the hub has selected. [env: PB_SLOT]
--wait, --no-wait: How long to stay with the program, and how much of the terminal to use while doing it. Left out, the session takes the terminal when there is one and returns straight away when there is not, since a script starting a stored program is setting a robot going. --wait stays either way, leaving the terminal alone and printing only the output. --no-wait always returns as soon as it starts. [env: PB_WAIT]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb stop¶

pb stop [OPTIONS]

Stop the program running on a hub.

Parameters:

--hub: Which hub, by name. Defaults to the one in use. [env: PB_HUB]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb check¶

pb check [OPTIONS] [ARGS]

Check that a program compiles, without sending it anywhere.

No hub and no background service: this is the compiler on its own. Useful while writing a program with no hub to hand, and as the fast check to put in a commit hook or a build, where starting a Bluetooth connection to find out about a missing bracket would be absurd.

It reports what the compiler said and how big the program came out, since size is the other thing that can stop a program running.

Arguments:

SCRIPT: The Python file to check. Leave it out when using --command. [env: PB_SCRIPT]

Parameters:

--command, -c: Python code to check, instead of a file. Like python -c. [env: PB_C]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv). [env: PB_V]

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb service¶

Manage the background service that keeps hubs connected.

Options:

--directory, -C: Work as if run from here, the way git -C does. Point it at the directory holding a project's pyproject.toml, or at the root of the source when there is no project file. It settles which project's settings apply, what a relative path means, and where a program's imports resolve from -- which is what makes a monorepo of several robot projects work from any shell. [env: PB_DIRECTORY]

pb service status¶

pb service status [OPTIONS]

Show whether the background service is running.

Parameters:

--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv).
--start, --no-start: Start the service if it is not running, instead of reporting that it is not. [default: False]

pb service start¶

pb service start [OPTIONS]

Start the background service if it is not already running.

Parameters:

--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv).

pb service stop¶

pb service stop [OPTIONS]

Stop the background service, disconnecting any hubs.

Parameters:

--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv).

pb service log¶

pb service log [OPTIONS]

Show what the background service has been doing.

The service has no terminal of its own, so its log is the only place its side of the story is written down. This reads the file directly and never contacts the service, which means it still works when the service is not running -- which is when it is most likely to be wanted.

Parameters:

--lines: How many lines from the end to show. Zero shows the whole file. [default: 50]
--follow, --no-follow, -f: Keep watching, printing new lines as they arrive. Ctrl-C leaves. [default: False]
--verbose, -v: Increase log detail. Repeat for more (-v, -vv, -vvv).