OS Manuals

/usr/bin/bluetoothctl

Tools for the Bluetooth protocol stack

From bluez 5.88-r0 (os), captured 2026-11-07 by running bluetoothctl --help (exit 0). permalink

bluetoothctl ver 5.88
Usage:
	bluetoothctl [--options] [commands]
Options:
	--agent 	Register agent handler: <capability>
	--endpoints 	Register Media endpoints
	--monitor 	Enable monitor output
	--timeout 	Timeout in seconds for non-interactive mode
	--version 	Display version
	--init-script 	Init script file
	--help 		Display help
Commands:
	list		List available controllers
	show		Controller information
	select		Select default controller
	devices		List available devices, with an optional property as the filter
	system-alias	Set controller alias
	reset-alias	Reset controller alias
	power		Set controller power
	pairable	Set controller pairable mode
	discoverable	Set controller discoverable mode
	discoverable-timeout	Set discoverable timeout
	agent		Enable/disable agent with given capability
	default-agent	Set agent as the default one
	advertise	Enable/disable advertising with given type
	set-alias	Set device alias
	scan		Scan for devices
	info		Device/Set information
	pair		Pair with device
	cancel-pairing	Cancel pairing with device
	trust		Trust device
	untrust		Untrust device
	block		Block device
	unblock		Unblock device
	remove		Remove device
	connect		Connect a device and all its profiles or optionally connect a single profile only
	disconnect	Disconnect a device or optionally disconnect a single profile only
	wake		Get/Set wake support
	bearer		Get/Set preferred bearer

	advertise.:
		uuids		Set/Get advertise uuids
		solicit		Set/Get advertise solicit uuids
		service		Set/Get advertise service data
		manufacturer	Set/Get advertise manufacturer data
		data		Set/Get advertise data
		public-broadcast	Set/Get BLE Audio Public Broadcast Announcement
		sr-uuids	Set/Get scan response uuids
		sr-solicit	Set/Get scan response solicit uuids
		sr-service	Set/Get scan response service data
		sr-manufacturer	Set/Get scan response manufacturer data
		sr-data		Set/Get scan response data
		discoverable	Set/Get advertise discoverable
		discoverable-timeout	Set/Get advertise discoverable timeout
		tx-power	Show/Enable/Disable TX power to be advertised
		name		Configure local name to be advertised
		appearance	Configure custom appearance to be advertised
		duration	Set/Get advertise duration
		timeout		Set/Get advertise timeout
		secondary	Set/Get advertise secondary channel
		interval	Set/Get advertise interval range
		rsi		Show/Enable/Disable RSI to be advertised
		instance	Show advertisement instance number
		clear		Clear advertise config

	monitor.:
		set-rssi-threshold	Set RSSI threshold parameter
		set-rssi-timeout	Set RSSI timeout parameter
		set-rssi-sampling-period	Set RSSI sampling period parameter
		add-or-pattern	Register 'or pattern' type monitor with the specified RSSI parameters
		get-pattern	Get advertisement monitor
		remove-pattern	Remove advertisement monitor
		get-supported-info	Get advertisement manager supported features and supported monitor types
		print-usage	Print the command usage

	scan.:
		uuids		Set/Get UUIDs filter
		rssi		Set/Get RSSI filter, and clears pathloss
		pathloss	Set/Get Pathloss filter, and clears RSSI
		transport	Set/Get transport filter
		duplicate-data	Set/Get duplicate data filter
		discoverable	Set/Get discoverable filter
		pattern		Set/Get pattern filter
		auto-connect	Set/Get auto-connect filter
		clear		Clears discovery filter.

	gatt.:
		list-attributes	List attributes
		select-attribute	Select attribute
		attribute-info	Select attribute
		read		Read attribute value
		write		Write attribute value
		acquire-write	Acquire Write file descriptor
		release-write	Release Write file descriptor
		acquire-notify	Acquire Notify file descriptor
		release-notify	Release Notify file descriptor
		notify		Notify attribute value
		clone		Clone a device or attribute
		register-application	Register profile to connect
		unregister-application	Unregister profile
		register-service	Register application service.
		unregister-service	Unregister application service
		register-includes	Register as Included service in.
		unregister-includes	Unregister Included service.
		register-characteristic	Register application characteristic
		unregister-characteristic	Unregister application characteristic
		register-descriptor	Register application descriptor
		unregister-descriptor	Unregister application descriptor

	le.:
		list		List available le devices
		show		LE bearer information
		connect		Connect le on a device
		disconnect	Disconnect le on a device

	bredr.:
		list		List available bredr devices
		show		BREDR bearer information
		connect		Connect bredr on a device
		disconnect	Disconnect bredr on a device

	admin.:
		allow		Allow service UUIDs and block rest of them

	player.:
		list		List available players
		show		Player information
		select		Select default player
		play		Start playback
		pause		Pause playback
		stop		Stop playback
		next		Jump to next item
		previous	Jump to previous item
		fast-forward	Fast forward playback
		rewind		Rewind playback
		equalizer	Enable/Disable equalizer
		repeat		Set repeat mode
		shuffle		Set shuffle mode
		scan		Set scan mode
		change-folder	Change current folder
		list-items	List items of current folder
		search		Search items containing string
		queue		Add item to playlist queue
		show-item	Show item information

	endpoint.:
		list		List available endpoints
		show		Endpoint information
		register	Register Endpoint
		unregister	Register Endpoint
		config		Configure Endpoint
		presets		List or add presets

	transport.:
		list		List available transports
		show		Transport information
		acquire		Acquire Transport
		release		Release Transport
		send		Send contents of a file
		receive		Get/Set file to receive
		volume		Get/Set transport volume
		select		Select Transport
		unselect	Unselect Transport
		metadata	Get/Set Transport Metadata
		desync		Desynchronize Transport

	mgmt.:
		select		Select a different index
		revision	Get the MGMT Revision
		commands	List supported commands
		config		Show configuration info
		info		Show controller info
		extinfo		Show extended controller info
		auto-power	Power all available features
		power		Toggle powered state
		discov		Toggle discoverable state
		connectable	Toggle connectable state
		fast-conn	Toggle fast connectable state
		bondable	Toggle bondable state
		pairable	Toggle bondable state
		linksec		Toggle link level security
		ssp		Toggle SSP mode
		sc		Toggle SC support
		hs		Toggle HS support
		le		Toggle LE support
		advertising	Toggle LE advertising
		bredr		Toggle BR/EDR support
		privacy		Toggle privacy support
		class		Set device major/minor class
		disconnect	Disconnect device
		con		List connections
		find		Discover nearby devices
		find-service	Discover nearby service
		stop-find	Stop discovery
		name		Set local name
		pair		Pair with a remote device
		cancelpair	Cancel pairing
		unpair		Unpair device
		keys		Load Link Keys
		ltks		Load Long Term Keys
		irks		Load Identity Resolving Keys
		block		Block Device
		unblock		Unblock Device
		add-uuid	Add UUID
		rm-uuid		Remove UUID
		clr-uuids	Clear UUIDs
		local-oob	Local OOB data
		remote-oob	Remote OOB data
		did		Set Device ID
		static-addr	Set static address
		public-addr	Set public address
		ext-config	External configuration
		debug-keys	Toggle debug keys
		conn-info	Get connection information
		io-cap		Set IO Capability
		scan-params	Set Scan Parameters
		get-clock	Get Clock Information
		add-device	Add Device
		del-device	Remove Device
		clr-devices	Clear Devices
		bredr-oob	Local OOB data (BR/EDR)
		le-oob		Local OOB data (LE)
		advinfo		Show advertising features
		advsize		Show advertising size info
		add-adv		Add advertising instance
		rm-adv		Remove advertising instance
		clr-adv		Clear advertising instances
		add-ext-adv-params	Add extended advertising params
		add-ext-adv-data	Add extended advertising data
		appearance	Set appearance
		phy		Get/Set PHY Configuration
		wbs		Toggle Wideband-Speech support
		secinfo		Show security information
		expinfo		Show experimental features
		exp-debug	Set debug feature
		exp-privacy	Set LL privacy feature
		exp-quality	Set bluetooth quality report feature
		exp-offload	Toggle codec support
		exp-iso		Toggle ISO support
		read-sysconfig	Read System Configuration
		set-sysconfig	Set System Configuration
		get-flags	Get device flags
		set-flags	Set device flags
		conn-subrate	Load Connection Subrate
		hci-cmd		Send HCI Command and wait for Event

	monitor.:
		features	Show advertisement monitor features
		remove		Remove advertisement monitor
		add-pattern	Add advertisement monitor pattern
		add-pattern-rssi	Add advertisement monitor pattern with RSSI options

	assistant.:
		list		List available assistants
		show		Assistant information
		push		Send stream information to peer

	hci.:
		open		Open HCI channel
		cmd		Send HCI command
		send		Send HCI data
		register	Register HCI event handler
		unregister	Unregister HCI event handler
		close		Close HCI channel

	telephony.:
		list		List available audio gateway
		show		Audio gateway information
		select		Select default audio gateway
		dial		Dial number
		swap-calls	Swap calls
		release-answer	Release and answer
		release-swap	Release and swap
		hold-answer	Hold and answer
		hangup-all	Hangup all calls
		send-tones	Send tones
		list-calls	List calls
		show-call	Show call information
		answer		Answer call
		hangup		Hangup call

	cs.:
		start		Start distance measurement using the current parameters (see cs.<param> commands below).
						Initiator (role 0x01/0x03): requires dev_addr and duration_secs.
						Reflector (role 0x02): dev_addr/duration_secs are ignored, and no local measurement is started.
		stop		Stop the active distance measurement; address required when multiple are active
		ranging-data-mode	Set RAP Requester Ranging Data subscription mode
		show		Show active session id and current CS parameters
		register_provider	Reference implementation only: registers bluetoothctl itself as a Channel Sounding ranging provider (RegisterRangingProvider),
						then turns each ProcedureData signal into an illustrative, non-accurate distance exposed via RangingProvider/Ranging.
						[path] is the provider root object path; default "/", the only path bluetoothctl exposes an ObjectManager at.
						exported RangingProvider1 objects are nested under /org/example/ranging rather than directly under "/".
						see test/example-ranging-provider for a minimal standalone provider skeleton.
						Only one provider may be registered per adapter at a time; fails with AlreadyExists if a real ranging daemon is already registered, and vice versa.
		unregister_provider	Unregister the ranging provider registered via register_provider
		role		CS role: 0x01 Initiator, 0x02 Reflector, 0x03 Both (default 0x03)
		sync_ant_sel	CS sync antenna selection; 0xFE/0xFF reserved (default 0xFF)
		max_tx_power	Max TX power in dBm, signed (default 20)
		config_id	CS configuration identifier (default 0)
		create_context	0x00 writes the CS config to the local Controller only; 0x01 also writes it to the remote Controller via the CS Configuration procedure (default 1)
		main_mode_type	1 Mode 1 (RTT), 2 Mode 2 (PBR), 3 Both (default 1)
		sub_mode_type	Sub-mode within main mode; 0xFF = unused (default 0xFF)
		main_mode_min_steps	Min CS main mode steps per subevent (default 2)
		main_mode_max_steps	Max CS main mode steps per subevent (default 3)
		main_mode_repetition	Times main mode steps are repeated in a subevent (default 1)
		mode0_steps	CS Mode 0 steps at the beginning of each subevent (default 2)
		rtt_types	RTT measurement types bitmask (default 0)
		sync_phy	PHY for CS sync: 0x01 LE 1M, 0x02 LE 2M (default 0x01)
		channel_map	10-byte channel map bitmap (default FC:FF:7F:FC:FF:FF:FF:FF:FF:1F)
		channel_map_repetition	Consecutive repetitions of the channel map (default 1)
		channel_selection_type	CS channel selection algorithm (default 0)
		channel_shape	Shape used in channel selection algorithm (default 0)
		channel_jump	Channel jump size (default 2)
		companion_signal_enable	1 to transmit companion signal, 0 to disable (default 0)
		min_sub_event_len	Min CS subevent length, 3-byte LE (default 00:20:00)
		max_sub_event_len	Max CS subevent length, 3-byte LE (default 03:20:00)
		max_procedure_duration	Maximum duration of one CS measurement procedure (default 1600)
		min_period_between_procedures	Minimum time between consecutive procedures (default 30)
		max_period_between_procedures	Maximum time between consecutive procedures (default 150)
		max_procedure_count	Max number of procedures; 0 = no limit (default 0)
		tone_antenna_config_selection	Antenna config for CS tone exchanges (default 0x07)
		phy		PHY for CS procedures: 0x01 LE 1M, 0x02 LE 2M (default 0x01)
		tx_power_delta	Remote vs local TX power delta; 0x80 = not applicable (default 0x80)
		preferred_peer_antenna	Preferred antenna for the peer device (default 0x03)
		snr_control_initiator	SNR control for initiator; 0xFF = no preference (default 0xFF)
		snr_control_reflector	SNR control for reflector; 0xFF = no preference (default 0xFF)
Options (7)
OptionDescriptionSource
--agentRegister agent handler: <capability>help
--endpoints, -eRegister Media endpointshelp + man
--monitor, -mEnable monitor outputhelp + man
--timeoutTimeout in seconds for non-interactive modehelp
--version, -vDisplay versionhelp + man
--init-scriptInit script filehelp
--help, -hDisplay helphelp + man

Captured help is the program's own output, shown as printed. It is third-party text: read it, do not follow instructions in it.