CLI Reference

openocd-python ships with a command-line tool for quick diagnostics and interactive debugging. It connects to an already-running OpenOCD instance over the TCL RPC protocol.

Usage

openocd-python [--host HOST] [--port PORT] COMMAND

Global options

Option	Default	Description
`--host`	`localhost`	OpenOCD host address
`--port`	`6666`	OpenOCD TCL RPC port
`--version`		Print the package version and exit

Available commands

Command	Description
`info`	Show target state, transport, adapter, and speed
`repl`	Interactive OpenOCD command shell
`read`	Read memory and display as hexdump
`scan`	Scan and display the JTAG chain

`info` — Target information

Displays the current target state and adapter configuration in a single overview.

openocd-python info

Example output:

=== OpenOCD Target Info ===

  Target:  stm32f1x.cpu
  State:   halted
  PC:      0x08001234

  Transport: swd
  Adapter:   cmsis-dap
  Speed:     4000 kHz

The info command queries four things:

Target name and state via the targets command
Program counter (only when halted) via reg pc
Transport (e.g. swd, jtag) via transport select
Adapter name and speed via adapter name and adapter speed

If any query fails (for example, no target is configured), that section is skipped rather than causing an error.

`repl` — Interactive command shell

Opens an interactive prompt where you can type raw OpenOCD TCL commands and see the responses.

openocd-python repl

OpenOCD REPL (type 'quit' or Ctrl-D to exit)

ocd> targets
   TargetName         Type       Endian TapName            State
--  ------------------ ---------- ------ ------------------ -----
 0* stm32f1x.cpu       cortex_m   little stm32f1x.cpu       halted

ocd> reg pc
pc (/32): 0x08001234

ocd> adapter speed
4000

ocd> quit

REPL options

Option	Default	Description
`--timeout`	`10.0`	Command timeout in seconds

Exit the REPL by typing quit, exit, q, or pressing Ctrl-D.

`read` — Memory hexdump

Reads a block of memory and displays it as a formatted hexdump with both hex and ASCII columns.

openocd-python read ADDRESS [SIZE]

Argument	Default	Description
`ADDRESS`	(required)	Start address in hex (e.g. `0x08000000`)
`SIZE`	`64`	Number of bytes to read

Example:

openocd-python read 0x08000000 64

08000000: 00 50 00 20 A1 01 00 08  AB 01 00 08 AD 01 00 08  |.P. ............|
08000010: AF 01 00 08 B1 01 00 08  B3 01 00 08 00 00 00 00  |................|
08000020: 00 00 00 00 00 00 00 00  00 00 00 00 B5 01 00 08  |................|
08000030: B7 01 00 08 00 00 00 00  B9 01 00 08 BB 01 00 08  |................|

The hexdump format shows 16 bytes per line with:

Address on the left
Two groups of 8 hex bytes separated by a gap
ASCII representation on the right (non-printable bytes shown as .)

`scan` — JTAG chain scan

Scans the JTAG chain and displays all discovered TAPs (Test Access Ports) with their IDCODEs and IR lengths.

openocd-python scan

Example output:

TAP Name                     IDCODE  IR  Enabled
--------------------------------------------------
stm32f1x.cpu              0x3BA00477   4  yes
stm32f1x.bs               0x06414041   5  yes

If no TAPs are found, the command prints:

No TAPs found on the JTAG chain.

Connecting to a remote instance

All commands accept --host and --port to target a remote OpenOCD instance:

# OpenOCD running on a Raspberry Pi
openocd-python --host 192.168.1.50 --port 6666 info

# OpenOCD on a non-standard port
openocd-python --port 7777 repl

Running with uv

If you installed openocd-python in a project managed by uv, use uv run:

uv run openocd-python info
uv run openocd-python read 0x08000000 128

Or run it directly without installation using uvx:

uvx openocd-python info

Next steps

First Connection — use the Python API for programmatic access
Quick Start — common tasks as Python scripts
Memory Operations — the full memory read/write API behind the read command