ffx

Fuchsia's developer tool


Usage: ffx [-c <config...>] [-e <env>] [--machine <machine>] [--schema] [--stamp <stamp>] [-t <target>] [--timeout <timeout>] [-l <log-level>] [--isolate-dir <isolate-dir>] [-v] [-o <log-output>] [--no-environment] [--strict] [subcommand...]
Options  
--help display usage information
-c, --config override configuration values (key=value, JSON string, or path to a JSON config file)
-e, --env override the path to the environment configuration file (file path)
--machine produce output for a machine in the specified format; available formats: "json", "json-pretty"
--schema produce the JSON schema for the MachineWriter output. The --machine option is required when producing the schema.
--stamp create a stamp file at the given path containing the exit code
-t, --target apply operations across single or multiple targets
--timeout override default proxy timeout (default is 1 second)
-l, --log-level sets the log level for ffx output (default = Info). Other possible values are Info, Error, Warn, and Trace. Can be persisted via log.level config setting.
--isolate-dir turn on isolation mode using the given directory to isolate all config and socket files into the specified directory. This overrides the FFX_ISOLATE_DIR env variable, which can also put ffx into this mode.
-v, --verbose logs ffx output to stdio according to log level
-o, --log-output specify destination of log output. "-" or "stdout" for stdout, "stderr" for stderr. If no destination is specified, log.dir will be used. If a destination is specified, then log.dir will be ignored.
--no-environment disables loading configuration from the file system and only uses configuration specified on the command line or the compiled in default values. Intended for use when running ffx as part of a hermetic build.
--strict switch which enables the 'strict' feature set. When set, ffx has stricter behavioual patterns. Including but not limited to: * Not doing discovery * Not starting the daemon * Communicating directly with the target from the ffx cli (not the daemon) * Configuration is read only The features in this flag are currently under active development.
Subcommands  
agis Agis Service
assembly Assemble images
audio Interact with the audio subsystem.
auth Generate Fuchsia authorization credentials.
bluetooth Issue a command to Sapphire, the Bluetooth system.
component Discover and manage components
config View and switch default and user configurations
coverage Show coverage from test outputs
daemon Interact with/control the ffx daemon
debug Start a debugging session.
doctor Run common checks for the ffx tool and host environment
driver Support driver development workflows
echo run echo test against the daemon
efi Manipulate efi partition
emu Start and manage Fuchsia emulators.
fuzz Start and manage fuzzers.
inspect Query data exposed by components via the Inspect API.
log Display logs from a target device
net View and manage target network configuration
package Create and publish Fuchsia packages
platform Manage platform build prerequisites
power Control system power features
process Processes related commands
product Discover and access product bundle metadata and image data.
profile Profile run-time information from various subsystems
profiler Interact with the profiling subsystem.
repository Inspect and manage package repositories
scrutiny Audit the security of Fuchsia
sdk Modify or query the installed SDKs
session Control the session component.
setui Modify and query settings.
starnix Control starnix containers
storage Manage Fuchsia Filesystems.
target Interact with a target device or emulator
target-package Interact with the target's packaging system
test Run test suite
trace Tracing is a tool that allows you to collect, aggregate, and visualize diagnostic tracing information from both userspace processes and the Zircon kernel on a Fuchsia device.
triage Analyze Logs and Inspect in snapshots to find problems.
version Print out ffx tool and daemon versions
wlan Developer tool for manipulating WLAN state.

agis

Agis Service


Usage:  ffx agis [subcommand...]
Options  
--help display usage information
Subcommands  
listen initiate listening on
register register a process with AGIS for tracing
shutdown shutdown all listeners
vtcs list all vulkan traceable components

listen

initiate listening on |global_id|


Usage:  ffx agis listen global_id
Options  
--help display usage information

register

register a process with AGIS for tracing


Usage:  ffx agis register id process_koid process_name
Options  
--help display usage information

shutdown

shutdown all listeners


Usage:  ffx agis shutdown
Options  
--help display usage information

vtcs

list all vulkan traceable components


Usage:  ffx agis vtcs
Options  
--help display usage information

assembly

Assemble images


Usage:  ffx assembly [subcommand...]
Options  
--help display usage information
Subcommands  
board-input-bundle Arguments for creating a Board Input Bundle for use by Assembly.
create-system create the system images.
create-update construct an UpdatePackage using images and package.
product Arguments for performing a high-level product assembly operation.
size-check Perform size checks (on packages or product based on the sub-command).

board-input-bundle

Arguments for creating a Board Input Bundle for use by Assembly.


Usage:  ffx assembly board-input-bundle --outdir <outdir> [--depfile <depfile>] [--drivers <drivers>] [--base-packages <base-packages...>] [--bootfs-packages <bootfs-packages...>] [--cpu-manager-config <cpu-manager-config>] [--energy-model-config <energy-model-config>] [--kernel-boot-args <kernel-boot-args...>] [--power-manager-config <power-manager-config>] [--power-metrics-recorder-config <power-metrics-recorder-config>] [--system-power-mode-config <system-power-mode-config>] [--thermal-config <thermal-config>] [--thread-roles <thread-roles...>] [--sysmem-format-costs-config <sysmem-format-costs-config...>]
Options  
--help display usage information
--outdir the directory to write the board input bundle to.
--depfile the path to write a depfile to, which contains all the files read in the process of creating the bundle. The output file listed in the depfile is '$outdir/board_input_bundle.json'.
--drivers the path to the file that describes all the drivers to add to the bundle. The format of this file is a json list of dictionaries that specify the following fields: 1) 'package': The path to the package manifest 2) 'set': The package set that it belongs to ("bootfs" or "base") 3) 'components': A list of the driver components in this pacakge.
--base-packages the paths to package manifests for all packages to add to the base package set.
--bootfs-packages the paths to package manifests for all packages to add to the bootfs package set.
--cpu-manager-config cpu-manager configuration
--energy-model-config energy model configuration for processor power management
--kernel-boot-args arguments to pass to the kernel on boot
--power-manager-config power-manager configuration
--power-metrics-recorder-config power metrics recorder configuration
--system-power-mode-config system power modes configuration
--thermal-config thermal management configuration
--thread-roles thread role configuration files
--sysmem-format-costs-config sysmem format costs configuration files Each file's content bytes are a persistent fidl fuchsia.sysmem2.FormatCosts. Normally json[5] would be preferable for config, but we generate this config in rust using FIDL types (to avoid repetition and to take advantage of FIDL rust codegen), and there's no json schema for FIDL types.

create-system

create the system images.


Usage:  ffx assembly create-system --image-assembly-config <image-assembly-config> [--include-account] --outdir <outdir> [--gendir <gendir>] [--base-package-name <base-package-name>]
Options  
--help display usage information
--image-assembly-config the configuration file that specifies the packages, binaries, and settings specific to the product being assembled.
--include-account whether to include an account partition in the FVMs.
--outdir the directory to write assembled outputs to.
--gendir the directory to write generated intermediate files to.
--base-package-name name to give the Base Package. This is useful if you must publish multiple base packages to the same TUF repository.

create-update

construct an UpdatePackage using images and package.


Usage:  ffx assembly create-update --partitions <partitions> [--system-a <system-a>] [--system-r <system-r>] --board-name <board-name> --version-file <version-file> --epoch <epoch> [--rewrite-default-repo <rewrite-default-repo>] [--subpackage-blobs-package-name <subpackage-blobs-package-name>] [--update-package-name <update-package-name>] --outdir <outdir> [--gendir <gendir>]
Options  
--help display usage information
--partitions path to a partitions config, which specifies where in the partition table the images are put.
--system-a path to an images manifest, which specifies images to put in slot A.
--system-r path to an images manifest, which specifies images to put in slot R.
--board-name name of the board. Fuchsia will reject an Update Package with a different board name.
--version-file file containing the version of the Fuchsia system.
--epoch backstop OTA version. Fuchsia will reject updates with a lower epoch.
--rewrite-default-repo rewrite package repository URLs to use this package URL hostname.
--subpackage-blobs-package-name name to give the Subpackage Blobs Package. This is currently only used by OTA tests to allow publishing multiple subpackage blob packages to the same amber repository without naming collisions.
--update-package-name name to give the Update Package. This is currently only used by OTA tests to allow publishing multiple update packages to the same amber repository without naming collisions.
--outdir directory to write the UpdatePackage.
--gendir directory to write intermediate files.

product

Arguments for performing a high-level product assembly operation.


Usage:  ffx assembly product --product <product> --board-info <board-info> --outdir <outdir> [--gendir <gendir>] --input-bundles-dir <input-bundles-dir> [--legacy-bundle <legacy-bundle>] [--package-validation <package-validation>] [--custom-kernel-aib <custom-kernel-aib>] [--developer-overrides <developer-overrides>]
Options  
--help display usage information
--product the configuration file that describes the product assembly to perform.
--board-info the file containing information about the board that the product is being assembled to run on.
--outdir the directory to write assembled outputs to.
--gendir the directory to write generated intermediate files to.
--input-bundles-dir the directory in which to find the platform assembly input bundles
--legacy-bundle the path to the legacy assembly input bundle directory
--package-validation disable validation of the assembly's packages
--custom-kernel-aib path to an AIB containing a customized kernel zbi to use instead of the one in the platform AIBs.
--developer-overrides path to a file specifying developer-level overrides for assembly.

size-check

Perform size checks (on packages or product based on the sub-command).


Usage:  ffx assembly size-check [subcommand...]
Options  
--help display usage information
Subcommands  
package Measure package sizes and verify they fit in the specified budgets. Exit status is 2 when one or more budgets are exceeded, and 1 when a failure prevented the budget verification to happen.
product (Not implemented yet) Check that the set of all blobs included in the product fit in the blobfs capacity.

package

Measure package sizes and verify they fit in the specified budgets. Exit status is 2 when one or more budgets are exceeded, and 1 when a failure prevented the budget verification to happen.


Usage:  ffx assembly size-check package --budgets <budgets> [--blob-sizes <blob-sizes...>] [--blobfs-layout <blobfs-layout>] [--gerrit-output <gerrit-output>] [-v] [--verbose-json-output <verbose-json-output>]
Options  
--help display usage information
--budgets path to a JSON file containing the list of size budgets. Each size budget has a name, a size which is the maximum number of bytes, and packages a list of path to manifest files.
--blob-sizes path to a blobs.json file. It provides the size of each blob composing the package on device.
--blobfs-layout the layout of blobs in blobfs.
--gerrit-output path where to write the verification report, in JSON format.
-v, --verbose show the storage consumption of each component broken down by package regardless of whether the component exceeded its budget.
--verbose-json-output path where to write the verbose JSON output.

product

(Not implemented yet) Check that the set of all blobs included in the product fit in the blobfs capacity.


Usage:  ffx assembly size-check product [--auth <auth>] --assembly-manifest <assembly-manifest> [--base-assembly-manifest <base-assembly-manifest>] [-v] [--visualization-dir <visualization-dir>] [--gerrit-output <gerrit-output>] [--size-breakdown-output <size-breakdown-output>] [--blobfs-creep-budget <blobfs-creep-budget>] [--platform-resources-budget <platform-resources-budget>]
Options  
--help display usage information
--auth use specific auth mode for oauth2 (see examples; default: pkce).
--assembly-manifest path to assembly_manifest.json.
--base-assembly-manifest path to the bast assembly_manifest.json which will be used to compare with the current assembly_manifest.json to produce a diff.
-v, --verbose whether to show the verbose output.
--visualization-dir path to the directory where HTML visualization should be stored.
--gerrit-output path where to write the gerrit size report.
--size-breakdown-output path where to write the size breakdown.
--blobfs-creep-budget maximum amount that the size of blobfs can increase in one CL. This value is propagated to the gerrit size report.
--platform-resources-budget maximum amount of bytes the platform resources can consume.

audio

Interact with the audio subsystem.


Usage:  ffx audio [subcommand...]
Options  
--help display usage information
Subcommands  
device Interact directly with device hardware.
gen Generate an audio signal. Outputs a WAV file written to stdout.
list-devices Prints all available audio devices on target
play Reads a WAV file from stdin and sends the audio data to audio_core AudioRenderer API.
record Records audio data from audio_core AudioCapturer API and outputs a WAV file to stdout.

Examples

Generate a 5s long audio signal with 440Hz frequency and write to a file: 
    $ ffx audio gen sine --frequency 440 --duration 5s --format 48000,uint8,1ch > ~/sine.wav 

Play a wav file using audio_core API: 
    $ cat ~/sine.wav | ffx audio play 

Record audio signal to a file using audio_core API: 
    $ ffx audio record --duration 1s --format 48000,uint8,1ch > ~/recording.wav

List available audio devices on target: 
    $ ffx audio device list

Print information about a specific audio device on target: 
    $ ffx audio device --name 3d99d780 info

Play a wav file directly to device hardware: 
    $ cat ~/sine.wav | ffx audio device play

Notes

  • Format parameters: Some commands take a --format= argument for describing audio PCM format.
The  argument has the pattern: ,,
    SampleRate: Integer
    SampleType options: uint8, int16, int32, float32
    Channels: ch

example: --format=48000,float32,2ch

device

Interact directly with device hardware.

The flags on the device command filter the list of available devices.

Commands that operate on a single device pick the first matching device, after filtering. For example, if the target has only one device, and no filter flags are provided, ffx audio device will use that device by default.


Usage:  ffx audio device [--name <name>] [--token-id <token-id>] [--direction <direction>] [--type <type>] [subcommand...]
Options  
--help display usage information
--name device devfs node name. e.g. 3d99d780 for the devfs path /dev/class/audio-input/3d99d780.
--token-id device token ID, for a device in the audio device registry. Only applies if the audio device registry is available on the target.
--direction device direction. Accepted values: input, output. Play and record will use output and input respectively by default.
--type device type. Accepted values: StreamConfig, Composite.
Subcommands  
agc Request to enable or disable automatic gain control for the stream.
gain Request to set the gain of the stream, in decibels.
info Show information about a specific audio device.
list Lists audio devices.
mute Request to mute a stream.
play Send audio data directly to device ring buffer.
record Capture audio data directly from ring buffer.
reset Reset device hardware.
set Set a device property.
start Start device hardware.
stop Stop device hardware.
unmute Request to unmute a stream.

Examples

Show information about a specific device:

    $ ffx audio device --name 3d99d780 --direction input info

Show information about a specific device in the audio device registry:

    $ ffx audio device --token-id 1 info

Play a WAV file directly to device hardware:

    $ cat ~/sine.wav | ffx audio device --name a70075f2 play
    $ ffx audio device --name a70075f2 play --file ~/sine.wav

Record a WAV file directly from device hardware:

    $ ffx audio device --name 3d99d780 record --format 48000,uint8,1ch --duration 1s

Mute the stream of an output device:

    $ ffx audio device --name a70075f2 --direction output mute

Set the gain of an output device to -20 dB:

    $ ffx audio device --name a70075f2 --direction output gain -20

Turn AGC on for an input device:

    $ ffx audio device --name 3d99d780 --direction input agc on

agc

Request to enable or disable automatic gain control for the stream.


Usage:  ffx audio device agc enable
Options  
--help display usage information

gain

Request to set the gain of the stream, in decibels.


Usage:  ffx audio device gain --gain <gain>
Options  
--help display usage information
--gain gain, in decibels, to set the stream to.

info

Show information about a specific audio device.


Usage:  ffx audio device info
Options  
--help display usage information

Examples

ffx audio device --type StreamConfig --direction input info

list

Lists audio devices.


Usage:  ffx audio device list
Options  
--help display usage information

Examples

ffx audio device --type StreamConfig list

mute

Request to mute a stream.


Usage:  ffx audio device mute
Options  
--help display usage information

play

Send audio data directly to device ring buffer.


Usage:  ffx audio device play [--file <file>] [--element-id <element-id>] [--channels <channels>]
Options  
--help display usage information
--file file in WAV format containing audio signal. If not specified, ffx command will read from stdin.
--element-id signal processing element ID, for an Endpoint element of type RingBuffer
--channels bitmask of channels to activate (deactivate the others). If not specified, activate all channels present in the playback format

record

Capture audio data directly from ring buffer.


Usage:  ffx audio device record [--duration <duration>] --format <format> [--element-id <element-id>]
Options  
--help display usage information
--duration duration of output signal. Examples: 5ms or 3s. If not specified, press ENTER to stop recording.
--format output format (see 'ffx audio help' for more information).
--element-id signal processing element ID, for an Endpoint element of type RingBuffer

reset

Reset device hardware.


Usage:  ffx audio device reset
Options  
--help display usage information

set

Set a device property.


Usage:  ffx audio device set [subcommand...]
Options  
--help display usage information
Subcommands  
dai-format Set the DAI format of device or signal processing element.
dai-format

Set the DAI format of device or signal processing element.


Usage:  ffx audio device set dai-format [--element-id <element-id>] format
Options  
--help display usage information
--element-id signal processing element ID, for an Endpoint element of type Dai

Examples

Set the DAI format for a specific Dai Endpoint signal processing element:

    $ ffx audio device set dai-format --element-id 2 48000,2ch,0x3,pcm_signed,16in16,i2s

Notes

  • This command accepts a DAI format as a comma separated string:

,,,,,

Where: : integer frame rate in Hz, e.g. 48000 ch: number of channels, e.g. 2ch : bitmask for channels that are in use, as a hexadecimal number prefixed with 0x, e.g. 0x3 for the first two channels, usually stereo left/right : sample format, one of: pdm, pcm_signed, pcm_unsigned, pcm_float : sample and slot size in bits as: in e.g. 16in32 for 16 valid sample bits in a 32 bit slot : frame format, either: a standard format, one of: none, i2s, stereo_left, stereo_right, tdm1, tdm2, tdm3 or a custom format: custom:;;; where: : justification of samples within a slot, one of: left_justified, right_justified : clocking of data samples, one of: raising_sclk, falling_sclk : number of sclks between the beginning of a frame sync change and audio samples. e.g. 1 for i2s, 0 for left justified : number of sclks that the frame sync is high. e.g. 1

Examples: 48000,2ch,0x3,pcm_signed,16in32,i2s 96000,1ch,0x1,pcm_float,32in32,custom:right_justified;falling_sclk;-1;0

start

Start device hardware.


Usage:  ffx audio device start
Options  
--help display usage information

stop

Stop device hardware.


Usage:  ffx audio device stop
Options  
--help display usage information

unmute

Request to unmute a stream.


Usage:  ffx audio device unmute
Options  
--help display usage information

gen

Generate an audio signal. Outputs a WAV file written to stdout.


Usage:  ffx audio gen [subcommand...]
Options  
--help display usage information
Subcommands  
pink-noise Generate pink noise.
sawtooth Generate a sawtooth wave signal.
sine Generate a sine wave signal.
square Generate a square wave signal.
triangle Generate a triangle wave signal.
white-noise Generate white noise.

Examples

ffx audio gen sine --duration 5ms --frequency 440 --amplitude 0.5 --format 48000,int16,2ch

pink-noise

Generate pink noise.


Usage:  ffx audio gen pink-noise --duration <duration> [--amplitude <amplitude>] --format <format>
Options  
--help display usage information
--duration duration of output signal. Examples: 5ms or 3s.
--amplitude signal amplitude in range [0, 1.0]. Default: 1.0.
--format output format (see 'ffx audio help' for more information).

sawtooth

Generate a sawtooth wave signal.


Usage:  ffx audio gen sawtooth --duration <duration> --frequency <frequency> [--amplitude <amplitude>] --format <format>
Options  
--help display usage information
--duration duration of output signal. Examples: 5ms or 3s.
--frequency frequency of output wave in Hz.
--amplitude signal amplitude in range [0, 1.0]. Default: 1.0.
--format output format (see 'ffx audio help' for more information).

sine

Generate a sine wave signal.


Usage:  ffx audio gen sine --duration <duration> --frequency <frequency> [--amplitude <amplitude>] --format <format>
Options  
--help display usage information
--duration duration of output signal. Examples: 5ms or 3s.
--frequency frequency of output wave in Hz.
--amplitude signal amplitude in range [0, 1.0]. Default: 1.0.
--format output format (see 'ffx audio help' for more information).

square

Generate a square wave signal.


Usage:  ffx audio gen square --duration <duration> --frequency <frequency> [--amplitude <amplitude>] [--duty-cycle <duty-cycle>] --format <format>
Options  
--help display usage information
--duration duration of output signal. Examples: 5ms or 3s.
--frequency frequency of output wave in Hz.
--amplitude signal amplitude in range [0, 1.0]. Default: 1.0.
--duty-cycle duty cycle in range [0, 1.0]. Default: 0.5.
--format output format (see 'ffx audio help' for more information).

triangle

Generate a triangle wave signal.


Usage:  ffx audio gen triangle --duration <duration> --frequency <frequency> [--amplitude <amplitude>] --format <format>
Options  
--help display usage information
--duration duration of output signal. Examples: 5ms or 3s.
--frequency frequency of output wave in Hz.
--amplitude signal amplitude in range [0, 1.0]. Default: 1.0.
--format output format (see 'ffx audio help' for more information).

white-noise

Generate white noise.


Usage:  ffx audio gen white-noise --duration <duration> [--amplitude <amplitude>] --format <format>
Options  
--help display usage information
--duration duration of output signal. Examples: 5ms or 3s.
--amplitude signal amplitude in range [0, 1.0]. Default: 1.0.
--format output format (see 'ffx audio help' for more information).

list-devices

Prints all available audio devices on target


Usage:  ffx audio list-devices
Options  
--help display usage information

Examples

$ ffx audio list-devices
$ ffx audio --machine json list-devices

play

Reads a WAV file from stdin and sends the audio data to audio_core AudioRenderer API.


Usage:  ffx audio play [--usage <usage>] [--buffer-size <buffer-size>] [--packet-count <packet-count>] [--gain <gain>] [--mute <mute>] [--clock <clock>] [--file <file>]
Options  
--help display usage information
--usage purpose of the stream being used to render audio.Accepted values: BACKGROUND, MEDIA, SYSTEM-AGENT, COMMUNICATION, INTERRUPTION,ULTRASOUND. Default: MEDIA.
--buffer-size buffer size (bytes) to allocate on device VMO.Used to send audio data from ffx tool to AudioRenderer.Defaults to size to hold 1 second of audio data.
--packet-count how many packets to use when sending data to an AudioRenderer.Defaults to 4 packets.
--gain gain (decibels) for the renderer. Default: 0 dB
--mute mute the renderer. Default: false
--clock explicitly set the renderer's reference clock. By default,SetReferenceClock is not called, which leads to a flexible clock. Options include: 'flexible', 'monotonic', and 'custom,,' where rate adjustment and offset are integers. To set offset without rate adjustment, pass 0in place of rate adjustment.
--file file in WAV format containing audio signal. If not specified,ffx command will read from stdin.

Examples

$ ffx audio gen sine --duration 1s --frequency 440 --amplitude 0.5 --format 48000,int16,2ch | ffx audio play 
$ ffx audio play --file ~/path/to/sine.wav

record

Records audio data from audio_core AudioCapturer API and outputs a WAV file to stdout.


Usage:  ffx audio record [--duration <duration>] --format <format> [--usage <usage>] [--buffer-size <buffer-size>] [--clock <clock>] [--gain <gain>] [--mute <mute>]
Options  
--help display usage information
--duration duration of output signal. Examples: 5ms or 3s. If not specified,press ENTER to stop recording.
--format output format (see 'ffx audio help' for more information).
--usage purpose of the stream being recorded.Accepted values: BACKGROUND, FOREGROUND, SYSTEM-AGENT, COMMUNICATION, ULTRASOUND,or LOOPBACK. Default: COMMUNICATION.
--buffer-size buffer size (bytes) to allocate on device VMO.Used to retrieve audio data from AudioCapturer.Defaults to size to hold 1 second of audio data.
--clock explicitly set the capturer's reference clock. By default,SetReferenceClock is not called, which leads to a flexible clock. Options include: 'flexible', 'monotonic', and 'custom,,' where rate adjustment and offset are integers. To set offset without rate adjustment, pass 0in place of rate adjustment.
--gain gain (decibels) for the capturer. Default: 0 dB
--mute mute the capturer. Default: false

Examples

$ ffx audio record --duration 1s --format 48000,uint8,1ch --usage SYSTEM-AGENT > ~/recording.wav

auth

Generate Fuchsia authorization credentials.


Usage:  ffx auth [subcommand...]
Options  
--help display usage information
Subcommands  
generate Generates authorization credentials for private Fuchsia artifacts

generate

Generates authorization credentials for private Fuchsia artifacts


Usage:  ffx auth generate [--auth <auth>]
Options  
--help display usage information
--auth choice of authentication flow, defaults to pkce which should be acceptable for most users.

Examples

ffx auth generate

bluetooth

Issue a command to Sapphire, the Bluetooth system.


Usage:  ffx bluetooth [subcommand...]
Options  
--help display usage information
Subcommands  
pandora Start/stop a Pandora gRPC test interface server and bluetooth-rootcanal virtual controller.
peer Show details for a known peer.

pandora

Start/stop a Pandora gRPC test interface server and bluetooth-rootcanal virtual controller.


Usage:  ffx bluetooth pandora [subcommand...]
Options  
--help display usage information
Subcommands  
start Start Pandora server and bluetooth-rootcanal.
stop Stop Pandora server and bt-rootcanal if running.

Examples

ffx bluetooth pandora start --rootcanal-ip 172.16.243.142

start

Start Pandora server and bluetooth-rootcanal.


Usage:  ffx bluetooth pandora start [--grpc-port <grpc-port>] --rootcanal-ip <rootcanal-ip> [--rootcanal-port <rootcanal-port>]
Options  
--help display usage information
--grpc-port the Fuchsia port on which the Pandora server will listen. Default: 8042.
--rootcanal-ip ip address of the host running the Rootcanal server.
--rootcanal-port port of Rootcanal server. Default: 6402.

Examples

ffx bluetooth pandora start --rootcanal-ip 172.16.243.142

stop

Stop Pandora server and bt-rootcanal if running.


Usage:  ffx bluetooth pandora stop
Options  
--help display usage information

peer

Show details for a known peer.


Usage:  ffx bluetooth peer [subcommand...]
Options  
--help display usage information
Subcommands  
list Show all known peers in a summarized view (optionally filtered).
show Show details for a known peer.

Examples

ffx bluetooth peer

list

Show all known peers in a summarized view (optionally filtered).


Usage:  ffx bluetooth peer list [--details] [filter]
Options  
--help display usage information
--details show details for all known peers

Examples

ffx bluetooth peer list

show

Show details for a known peer.


Usage:  ffx bluetooth peer show id_or_addr
Options  
--help display usage information

Examples

ffx bluetooth peer show

component

Discover and manage components


Usage:  ffx component [subcommand...]
Options  
--help display usage information
Subcommands  
capability Lists component instances that reference a capability
collection Manages collections in the component topology
config Manages configuration capability override values for components
copy copies files to/from directories associated with a component.
create Creates a dynamic component instance, adding it to the collection designated by
debug Debug a running component with zxdb.
destroy Destroys a dynamic component instance, removing it from the collection designated by
doctor Perform diagnostic checks on a component at runtime.
explore Spawns a shell scoped to a component instance.
graph Outputs a Graphviz dot graph for the components in the component topology. Children of unresolved components are not included in this list.
list Lists components in the component topology. Children of unresolved components are not included in this list.
reload Recursively stops, unresolves, and starts a component instance, updating the code and topology while preserving resources
resolve Resolves a component instance
route Perform capability routing on a component at runtime.
run Creates and starts a component instance in an existing collection
show Shows detailed information about a component instance
start Starts a component
stop Stops a component instance
storage Manages storage capabilities of components

capability

Lists component instances that reference a capability


Usage:  ffx component capability capability
Options  
--help display usage information

Examples

To show all components that reference a capability:

    $ ffx component capability fuchsia.net.routes

collection

Manages collections in the component topology


Usage:  ffx component collection [subcommand...]
Options  
--help display usage information
Subcommands  
list List all collections in the component topology
show Shows detailed information about a collection in the component topology

list

List all collections in the component topology


Usage:  ffx component collection list
Options  
--help display usage information

show

Shows detailed information about a collection in the component topology


Usage:  ffx component collection show query
Options  
--help display usage information

config

Manages configuration capability override values for components


Usage:  ffx component config [subcommand...]
Options  
--help display usage information
Subcommands  
list Lists structured configuration values for the specified component
set Sets configuration capability override values for the specified component
unset Unsets structured configuration override values for the specified component

list

Lists structured configuration values for the specified component


Usage:  ffx component config list query
Options  
--help display usage information

set

Sets configuration capability override values for the specified component


Usage:  ffx component config set [-r] query [key_values...]
Options  
--help display usage information
-r, --reload if enabled, component instance will be immediately reloaded so overrides take effect.

Examples

To override the configuration fields `bar` and `baz` for the component `/core/ffx-laboratory:foo`:

    $ ffx component config set /core/ffx-laboratory:foo bar=true baz=42

    Use the reload flag to cause the component to reload the component with the override in effect:

    $ ffx component config set --reload /core/ffx-laboratory:foo bar=true

    To override a vector configuration field, use a comma separated list:

    $ ffx component config set /core/ffx-laboratory:foo "some_list=1, 2, 3"

unset

Unsets structured configuration override values for the specified component


Usage:  ffx component config unset [-r] [query]
Options  
--help display usage information
-r, --reload if enabled, component instance will be immediately reloaded so overrides take effect.

Examples

To unset overrides for the component `core/ffx-laboratory:foo`

    $ ffx component config unset `core/ffx-laboratory:foo`

    To unset overrides for all components with overrides:

    $ ffx component config unset

copy

copies files to/from directories associated with a component. Paths may be any combination of local or remote paths.


Usage:  ffx component copy [-v] [paths...]
Options  
--help display usage information
-v, --verbose verbose output: outputs a line for each file copied.

Examples

To copy from a component to a local path: 
ffx component copy /some/moniker::/path/file.txt /local/file.txt 

To copy from a local path to a component: 
ffx component copy /local/file.txt /some/moniker::/dir/file.txt

To copy between two components: 
ffx component copy /some/moniker::/dir/file.txt /some/moniker::/dir/file.txt

To copy multiple files: 
ffx component copy /some/moniker::/dir/* /some/local/dir
ffx component copy /file/one.txt /file/two.txt ... /some/moniker::/dir/

To copy a file from a component's outgoing directory: 
ffx component copy /some/moniker::out::/path/file.txt /local/file.txt

To copy a file from a component's package directory: 
ffx component copy /some/moniker::pkg::/meta/foo /tmp

Notes

  • To learn more about the command see https://fuchsia.dev/fuchsia-src/development/sdk/ffx/copy-files-to-and-from-a-component

create

Creates a dynamic component instance, adding it to the collection designated by 


Usage:  ffx component create [--config <config...>] moniker url
Options  
--help display usage information
--config provide a configuration override to the component being run. Requires mutability: \[ "parent" ] on the configuration field. Specified in the format KEY=VALUE where VALUE is a JSON string which can be resolved as the correct type of configuration value.

Examples

To create a component instance designated by the moniker `/core/ffx-laboratory:foo`:

    $ ffx component create /core/ffx-laboratory:foo fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm

Notes

  • To learn more about running components, see https://fuchsia.dev/go/components/run

debug

Debug a running component with zxdb.


Usage:  ffx component debug query
Options  
--help display usage information

Examples

To debug the `brightness_manager` component instance, all of the
following commands are valid:

    $ ffx component debug /core/brightness_manager
    $ ffx component debug fuchsia-pkg://fuchsia.com/brightness_manager#meta/brightness_manager.cm
    $ ffx component debug meta/brightness_manager.cm
    $ ffx component debug brightness_manager

If the component is not yet running, consider `ffx component start --debug`
to start the component in the debugger.

Notes

  • This command supports partial matches over the moniker, URL and instance ID

destroy

Destroys a dynamic component instance, removing it from the collection designated by 


Usage:  ffx component destroy query
Options  
--help display usage information

Examples

To destroy a component instance designated by the moniker `/core/ffx-laboratory:foo`:

    $ ffx component destroy /core/ffx-laboratory:foo

Notes

  • To learn more about running components, see https://fuchsia.dev/go/components/run

doctor

Perform diagnostic checks on a component at runtime.


Usage:  ffx component doctor [-p] query
Options  
--help display usage information
-p, --plain whether or not to display the output without color and wrapping.

Examples

To run diagnostics:

$ ffx component doctor /core/network/netstack

This will run checks on the capabilities configuration of the component, checking that all of the
`use` and `expose` capabilities can be routed successfully by the component manager.

explore

Spawns a shell scoped to a component instance.


Usage:  ffx component explore [--tools <tools...>] [-c <command>] [-l <layout>] query
Options  
--help display usage information
--tools list of URLs of tools packages to include in the shell environment. the PATH variable will be updated to include binaries from these tools packages. repeat --tools url for each package to be included. The path preference is given by command line order.
-c, --command execute a command instead of reading from stdin. the exit code of the command will be forwarded to the host.
-l, --layout changes the namespace layout that is created for the shell. nested: nests all instance directories under subdirs (default) namespace: sets the instance namespace as the root (works better for tools)

Examples

To explore the Archivist instance interactively:

> ffx component explore /bootstrap/archivist
$ ls
exposed
ns
out
runtime
svc
$ exit
Connection to terminal closed

To run a command directly from the command line:
> ffx component explore /bootstrap/archivist -c 'printenv'
PATH=/.dash/tools/debug-dash-launcher
PWD=/

Notes

  • When --layout=nested (the default), the environment contains the following
directories of the explored instance:
  • /ns The namespace of the instance
  • /exposed The capabilities exposed by the instance
  • /out The outgoing directory of the instance, if it is running
  • /runtime The runtime directory of the instance, if it is running

The environment also contains the following directories, irrespective of the explored instance: * /.dash User-added and built-in dash tools * /svc Protocols required by the dash shell

When --layout=namespace, the contents of the /ns dir above are placed at / with two protocols (fuchsia.process.Launcher and fuchsia.process.Resolver) overlayed into /svc. In this mode, the exposed, out, and runtime directories will not be accessible.

With --tools, tools in the specified package will be loaded into /.dash/tools// The path is set so that they can be run by name. The path preference is in the command line order of the --tools arguments, with any built-in tools taking lowest priority.

--tools URLs may be package or binary URLs. If a package URL is given, tool executables are expected to be in a bin/ dir within the package. If a specific tool URL is given, append the tool path to the package URL. For example: --tools fuchsia-pkg://fuchsia.com/my_package#bin/my_tool. Note that naming collisions can occur if multiple packages share a package or binary name. An error, NonUniqueBinaryName, is returned if a binary name collision occurs.

graph

Outputs a Graphviz dot graph for the components in the component topology. Children of unresolved components are not included in this list.


Usage:  ffx component graph [-o <only>] [-r <orientation>]
Options  
--help display usage information
-o, --only filter the instance list by a criteria: ancestor, descendant, relative
-r, --orientation changes the visual orientation of the graph's nodes. Allowed values are "lefttoright"/"lr" and "toptobottom"/"tb".

Examples

To graph components in the topology:

    $ ffx component graph

    To graph all running components in the topology:

    $ ffx component graph --only running

    To graph all stopped components in the topology:

    $ ffx component graph --only stopped

    To graph the ancestors of a component named `foo`:

    $ ffx component graph --only ancestor:foo

    To graph the descendants of a component named `foo`:

    $ ffx component graph --only descendant:foo

    To graph both the ancestors and descendants of a component named `foo`:

    $ ffx component graph --only relatives:foo

    To order the graph's nodes from left-to-right (instead of top-to-bottom):

    $ ffx component graph --orientation left_to_right

list

Lists components in the component topology. Children of unresolved components are not included in this list.


Usage:  ffx component list [-o <only>] [-v]
Options  
--help display usage information
-o, --only filter the instance list by a criteria: running, stopped, ancestors:, descendants:, or relatives:
-v, --verbose show detailed information about each instance

Examples

To list components in the topology:

    $ ffx component list

    To list all running components in the topology:

    $ ffx component list --only running

    To list all stopped components in the topology:

    $ ffx component list --only stopped

    To list the ancestors of a component named `foo`:

    $ ffx component list --only ancestor:foo

    To list the descendants of a component named `foo`:

    $ ffx component list --only descendant:foo

    To list both the ancestors and descendants of a component named `foo`:

    $ ffx component list --only relatives:foo

reload

Recursively stops, unresolves, and starts a component instance, updating the code and topology while preserving resources


Usage:  ffx component reload query
Options  
--help display usage information

Examples

To reload a component instance designated by the moniker `/core/ffx-laboratory:foo`:

    $ ffx component reload /core/ffx-laboratory:foo

Notes

  • To learn more about running components, see https://fuchsia.dev/go/components/run

resolve

Resolves a component instance


Usage:  ffx component resolve query
Options  
--help display usage information

Examples

To resolve the component designated by the provided moniker `/core/brightness_manager`:

    $ ffx component resolve /core/brightness_manager

route

Perform capability routing on a component at runtime.


Usage:  ffx component route target [filter]
Options  
--help display usage information

Examples

To route capabilities from `font_provider`:

$ ffx component route /core/font_provider

This will perform routing on all the capabilities used or exposed by `font_provider`, and display
information for each route including its status (success or failure) and the identity of the source
component providing the capability.

$ ffx component route fonts.cm

This does the same thing, except with a fuzzy match (on the URL).

$ ffx component route /core/font_provider fuchsia.pkg.FontResolver

This will perform routing on capabilities used or exposed by `font_provider` that match
`fuchsia.pkg.FontResolver`.

$ ffx component route /core/font_provider use:fuchsia.pkg.FontResolver,expose:fuchsia.fonts.Provider

This will perform routing from `font_provider` on used capability `fuchsia.pkg.FontResolver` and
exposed capability `fuchsia.fonts.Provider`.

$ ffx component route /core/font_provider fuchsia.pkg

Fuzzy matching by capability is also supported. This will perform routing from `font_provider` on
any used or exposed capability matching *fuchsia.pkg*.

run

Creates and starts a component instance in an existing collection within the component topology.


Usage:  ffx component run [-r] [-f] [--connect-stdio] [--config <config...>] moniker url
Options  
--help display usage information
-r, --recreate destroy and recreate the component instance if it already exists
-f, --follow-logs start printing logs from the started component after it has started
--connect-stdio connect stdin, stdout, and stderr to the component (requires component to be in a collection with single_run durability)
--config provide a configuration override to the component being run. Requires mutability: \[ "parent" ] on the configuration field. Specified in the format KEY=VALUE where VALUE is a JSON string which can be resolved as the correct type of configuration value.

Examples

To create a component instance from the `hello-world-rust` component URL:

    $ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm

Notes

  • This command is a shorthand for the following:
    


    $ ffx component create  
$ ffx component start

To learn more about running components, see https://fuchsia.dev/go/components/run

show

Shows detailed information about a component instance


Usage:  ffx component show query
Options  
--help display usage information

Examples

To show information about the `brightness_manager` component instance, all of the
following commands are valid:

    $ ffx component show /core/brightness_manager
    $ ffx component show fuchsia-pkg://fuchsia.com/brightness_manager#meta/brightness_manager.cm
    $ ffx component show meta/brightness_manager.cm
    $ ffx component show brightness_manager

Notes

  • This command supports partial matches over the moniker, URL and instance ID

start

Starts a component


Usage:  ffx component start [--debug] query
Options  
--help display usage information
--debug start the component in the debugger. To debug a component that is already running, consider ffx component debug.

Examples

To start the component instance designated by the moniker `/core/brightness_manager`:

    $ ffx component start /core/brightness_manager

The start the brightness manager in the debugger, use the --debug flag:

    $ ffx component start /core/brightness_manager --debug

Notes

  • To learn more about running components, see https://fuchsia.dev/go/components/run

stop

Stops a component instance


Usage:  ffx component stop query
Options  
--help display usage information

Examples

To stop the component instance designated by the moniker `/core/brightness_manager`:

    $ ffx component stop /core/brightness_manager

Notes

  • To learn more about running components, see https://fuchsia.dev/go/components/run

storage

Manages storage capabilities of components


Usage:  ffx component storage [--provider <provider>] [--capability <capability>] [subcommand...]
Options  
--help display usage information
--provider the moniker of the storage provider component. Defaults to "/core"
--capability the capability name of the storage to use. Examples: "data", "cache", "tmp" Defaults to "data"
Subcommands  
copy Copy files to/from a component's storage. If the file already exists at the destination it is overwritten.
delete Delete files from a component's storage.
delete-all Delete the contents of the storage for a specific component.
list List the contents of a component's storage.
make-directory Create a new directory in a component's storage. If the directory already exists, this operation is a no-op.

copy

Copy files to/from a component's storage. If the file already exists at the destination it is overwritten.


Usage:  ffx component storage copy source_path destination_path
Options  
--help display usage information

Examples

To copy `credentials.json` from the current working directory on the host to the `settings` directory of a component's storage:

    $ ffx component storage copy ./credentials.json 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::settings/credentials.json

To copy `credentials.json` from the current working directory on the host to the `settings` directory from a different provider and capability:

    $ ffx component storage --provider /core/test_manager --capability data copy ./credentials.json f1a52f7b4d7081060a3295fd36df7b68fb0518f80aae0eae8a3fc1d55231375f::settings/credentials.json

Note: 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520 is the instance ID of
the component whose storage is being accessed.

To learn about component instance IDs, see https://fuchsia.dev/go/components/instance-id

delete

Delete files from a component's storage.


Usage:  ffx component storage delete path
Options  
--help display usage information

Examples

To delete `credentials.json` from the root directory of a component's persistent storage:

    $ ffx component storage delete 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::credentials.json

Note: 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520 is the instance ID of
the component whose storage is being accessed.

To learn about component instance IDs, see https://fuchsia.dev/go/components/instance-id

delete-all

Delete the contents of the storage for a specific component.


Usage:  ffx component storage delete-all moniker
Options  
--help display usage information

Examples

To delete the contents of the storage for a component with moniker `foo`:

    $ ffx component storage delete-all foo

Note: although unusual, the user may specify internal instance IDs in the moniker such as `foo:0/bar:2`.

list

List the contents of a component's storage.


Usage:  ffx component storage list path
Options  
--help display usage information

Examples

To list the contents of the `settings` directory in a component's storage:

    $ ffx component storage list 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::settings

To list the contents of the root directory of a component's storage:

    $ ffx component storage list 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::/

To list the contents of a directory using a different provider and capability:

    $ ffx component storage --provider /core/test_manager --capability data list f1a52f7b4d7081060a3295fd36df7b68fb0518f80aae0eae8a3fc1d55231375f::/

Note: 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520 is the instance ID of
the component whose storage is being accessed.

To learn about component instance IDs, see https://fuchsia.dev/go/components/instance-id

make-directory

Create a new directory in a component's storage. If the directory already exists, this operation is a no-op.


Usage:  ffx component storage make-directory path
Options  
--help display usage information

Examples

To make a `settings` directory in a storage:

    $ ffx component storage make-directory 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::settings

To make a `settings` directory in a storage from a different provider and capability:

    $ ffx component storage --provider /core/test_manager --capability data make-directory f1a52f7b4d7081060a3295fd36df7b68fb0518f80aae0eae8a3fc1d55231375f::settings

Note: 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520 is the instance ID of
the component whose storage is being accessed.

To learn about component instance IDs, see https://fuchsia.dev/go/components/instance-id

config

View and switch default and user configurations


Usage:  ffx config [subcommand...]
Options  
--help display usage information
Subcommands  
add add config value the end of an array
analytics enable or disable analytics
check-ssh-keys check the ssh key configuration and create keys if needed.
env list environment settings
get display config values
remove remove user level config values
set set config settings

add

add config value the end of an array


Usage:  ffx config add name value
Options  
--help display usage information

Notes

  • This will always add to the end of an array.  Adding to a subtree is not supported. If the current value is not an array, it will convert the value to an array.  If you want to insert a value in a different position, consider editing the configuration file directly.  Configuration file locations can be found by running ffx config env get command.

analytics

enable or disable analytics


Usage:  ffx config analytics [subcommand...]
Options  
--help display usage information
Subcommands  
disable disable analytics
enable enable basic (redacted) analytics
enable-enhanced enable enhanced analytics (Googlers only)
show show analytics

disable

disable analytics


Usage:  ffx config analytics disable
Options  
--help display usage information

enable

enable basic (redacted) analytics


Usage:  ffx config analytics enable
Options  
--help display usage information

enable-enhanced

enable enhanced analytics (Googlers only)


Usage:  ffx config analytics enable-enhanced
Options  
--help display usage information

show

show analytics


Usage:  ffx config analytics show
Options  
--help display usage information

check-ssh-keys

check the ssh key configuration and create keys if needed.


Usage:  ffx config check-ssh-keys
Options  
--help display usage information

env

list environment settings


Usage:  ffx config env [subcommand...]
Options  
--help display usage information
Subcommands  
get list environment for a given level
set set environment settings

get

list environment for a given level


Usage:  ffx config env get [level]
Options  
--help display usage information

set

set environment settings


Usage:  ffx config env set [-l <level>] file
Options  
--help display usage information
-l, --level config level. Possible values are "user", "build", "global". Defaults to "user".

get

display config values


Usage:  ffx config get [-p <process>] [-s <select>] [name]
Options  
--help display usage information
-p, --process how to process results. Possible values are "r/raw", "s/sub/substitute", or "f/file". Defaults to "substitute". Currently only supported if a name is given. The process type "file" returns a scalar value. In the case of the configuration being a list, it is treated as an ordered list of alternatives and takes the first value that exists.
-s, --select how to collect results. Possible values are "first" and "all". Defaults to "first". If the value is "first", the first value found in terms of priority is returned. If the value is "all", all values across all configuration levels are aggregrated and returned. Currently only supported if a name is given.
Errors  
2 No value found

remove

remove user level config values


Usage:  ffx config remove name
Options  
--help display usage information

Notes

  • This will remove the entire value for the given name.  If the value is a subtree or array, the entire subtree or array will be removed.  If you want to remove a specific value from an array, consider editing the configuration file directly.  Configuration file locations can be found by running ffx config env get command.

set

set config settings


Usage:  ffx config set name value
Options  
--help display usage information

coverage

Show coverage from test outputs


Usage:  ffx coverage --test-output-dir <test-output-dir> --clang-dir <clang-dir> [--symbol-index-json <symbol-index-json>] [--export-html <export-html>] [--export-lcov <export-lcov>] [--path-remappings <path-remappings...>] [--compilation-dir <compilation-dir>] [src_files...]
Options  
--help display usage information
--test-output-dir path to ffx test output directory
--clang-dir path to clang directory, llvm-profdata and llvm-cov are expected in clang_dir/bin
--symbol-index-json path to symbol index json to load symbol index from
--export-html directory to export HTML reports to
--export-lcov path to export LCOV file to
--path-remappings "," remapping of source file paths passed through to llvm-cov
--compilation-dir path to the directory used as a base for relative coverage mapping paths, passed through to llvm-cov

daemon

Interact with/control the ffx daemon


Usage:  ffx daemon [subcommand...]
Options  
--help display usage information
Subcommands  
crash crash the daemon
disconnect Disconnect from a target
echo run echo test against the daemon
hang hang the daemon
log Dumps the daemon log
socket query information about the daemon socket without connecting to it
start run as daemon -- normally unnecessary, as the daemon is automatically started on demand. Used primarily for debugging
stop stops a running daemon

crash

crash the daemon


Usage:  ffx daemon crash
Options  
--help display usage information

disconnect

Disconnect from a target


Usage:  ffx daemon disconnect
Options  
--help display usage information

Notes

  • Tells the daemon to disconnect from the specified target.
Useful when the client knows the connection is no longer valid, e.g.
in a test in which the target has been rebooted.

echo

run echo test against the daemon


Usage:  ffx daemon echo [text]
Options  
--help display usage information

hang

hang the daemon


Usage:  ffx daemon hang
Options  
--help display usage information

log

Dumps the daemon log


Usage:  ffx daemon log [-f] [-l <line-count>]
Options  
--help display usage information
-f, --follow print appended logs as they happen
-l, --line-count display most recent log lines.

socket

query information about the daemon socket without connecting to it


Usage:  ffx daemon socket
Options  
--help display usage information

start

run as daemon -- normally unnecessary, as the daemon is automatically started on demand. Used primarily for debugging


Usage:  ffx daemon start [--path <path>] [-b]
Options  
--help display usage information
--path override the path the socket will be bound to
-b, --background runs the daemon in the background. Returns after verifying daemon connection. No-op if the daemon is already running.

stop

stops a running daemon


Usage:  ffx daemon stop [-w] [--no-wait] [-t <timeout-ms>]
Options  
--help display usage information
-w, --wait wait indefinitely for the daemon to stop before exiting (should not be used in automated systems)
--no-wait do not wait for daemon to stop (default behavior -- eventually to be deprecated)
-t, --timeout-ms optional timeout (in milliseconds) to wait for the daemon to stop. Will try killing the daemon if it does not exit on its own.

debug

Start a debugging session.


Usage:  ffx debug [subcommand...]
Options  
--help display usage information
Subcommands  
connect start the debugger and connect to the target
core start the debugger and open a minidump
crash catch a crashing process on the target
fidl monitor FIDL traffic on the target
limbo control the process limbo on the target
symbol-index manage symbol sources used by other debug commands
symbolize symbolize backtraces in markup format

connect

start the debugger and connect to the target


Usage:  ffx debug connect [--debugger <debugger>] [--agent-only] [-a <attach...>] [-e <execute...>] [--new-agent] [zxdb_args...]
Options  
--help display usage information
--debugger start zxdb in another debugger. Currently, the only valid option is "lldb".
--agent-only only start the debug agent but not the zxdb. The path to the UNIX socket will be printed and can be connected via "connect -u" in zxdb shell.
-a, --attach attaches to given processes. The argument will be parsed in the same way as the "attach" command in the console.
-e, --execute execute one zxdb command. Multiple commands will be executed sequentially.
--new-agent always spawn a new DebugAgent instance for this zxdb invocation.

core

start the debugger and open a minidump


Usage:  ffx debug core [--zxdb-args <zxdb-args...>] [minidump]
Options  
--help display usage information
--zxdb-args extra arguments passed to zxdb.

crash

catch a crashing process on the target


Usage:  ffx debug crash
Options  
--help display usage information

fidl

monitor FIDL traffic on the target


Usage:  ffx debug fidl [--from <from>] [--to <to>] [--format <format>] [--with <with...>] [--with-process-info] [--stack <stack>] [--syscalls <syscalls...>] [--exclude-syscalls <exclude-syscalls...>] [--messages <messages...>] [--exclude-messages <exclude-messages...>] [--trigger <trigger...>] [--thread <thread...>] [--dump-messages] [--remote-pid <remote-pid...>] [-f <remote-name...>] [--extra-name <extra-name...>] [-c <remote-component...>] [--extra-component <extra-component...>] [--fidl-ir-path <fidl-ir-path...>] [extra_args...]
Options  
--help display usage information
--from specifies the source. Source can be: device: this is the default input. The input comes from the live monitoring of one or several processes. At least one of '--remote-pid', '--remote-name', '--remote-job-id', --'remote-job-name', 'run' must be specified. dump: The input comes from stdin which is the log output of one or several programs. The lines in the log which dump syscalls are decoded and replaced by the decoded version. All other lines are unchanged. : playback. Used to replay a session previously recorded with --to (protobuf format). Path gives the name of the file to read. If path is '-' then the standard input is used. This option must be used at most once.
--to the session is saved to the specified file (binary protobuf format). When a session is saved, you can replay it using "--from ". The raw data is saved. That means that the data saved is independent from what is displayed.
--format the display format for the session dump. The available formats are: pretty: the session is pretty printed (with colors). This is the default output if --with is not used. json: the session is printed using a json format. textproto: the session is printed using a text protobuf format. none: nothing is displayed on the standard output (this option only makes sense when used with --to or with --with). When there is no output, fidlcat is faster (this is better to monitor real time components). This is the default output when --with is used.
--with specifies an extra summarized output. summary: at the end of the session, a summary of the session is displayed on the standard output. top: at the end of the session, generate a view that groups the output by process, protocol, and method. The groups are sorted by number of events, so groups with more associated events are listed earlier. group-by-thread: for each thread display a short version of all the events. An equal sign followed by a path can be concatanated to the option to output the result in a file instead of the standard output (for example: --with summary=/tmp/x). This option can be used several times.
--with-process-info display the process name, process id and thread id on each line (useful for grep).
--stack define the amount of stack frame to display 0: none (default value) 1: call site (1 to 4 levels) 2: full stack frame (adds some overhead)
--syscalls a regular expression which selects the syscalls to decode and display. This option can be specified multiple times. By default, only zxchannel.* syscalls are displayed. To display all the syscalls, use: --syscalls ".*"
--exclude-syscalls a regular expression which selects the syscalls to not decode and display. This option can be specified multiple times. To be displayed, a syscall must verify --syscalls and not verify --exclude-syscalls. To display all the syscalls but the zx_handle syscalls, use: --syscalls "." --exclude-syscalls "zxhandle."
--messages a regular expression which selects the messages to display. To display a message, the method name must satisfy the regexp. This option can be specified multiple times. Message filtering works on the method's fully qualified name.
--exclude-messages a regular expression which selects the messages to not display. If a message method name satisfy the regexp, the message is not displayed (even if it satisfies --messages). This option can be specified multiple times. Message filtering works on the method's fully qualified name.
--trigger start displaying messages and syscalls only when a message for which the method name satisfies the filter is found. This option can be specified multiple times. Message filtering works on the method's fully qualified name.
--thread only display the events for the specified thread. This option can be specified multiple times. By default all the events are displayed.
--dump-messages always does a hexadecimal dump of the messages even if we can decode them.
--remote-pid the koid of the remote process to trace.
-f, --remote-name the of a process. Fidlcat will monitor all existing and future processes whose names includes ( is a substring of the process name). This option can be specified multiple times. When used with --remote-job-id or --remote-job-name, only the processes from the selected jobs are taken into account.
--extra-name like "--remote-name" but for these processes, monitoring starts only when one of the "--remote-name" or "--remote-component" is launched. Also, fidlcat stops when the last "--remote-name" or "--remote-component" stops, even if some "--extra-name" processes are still running. You must specify at least one filter with "--remote-name" or "--remote-component" if you use this option. This option can be specified multiple times.
-c, --remote-component the URL or the moniker of a component for which we want to monitor. All processes running in the component will be monitered. This option can be specified multiple times.
--extra-component like "--remote-component" but for these components, monitoring starts only when one of the "--remote-name" or "--remote-component" is launched. Also, fidlcat stops when the last "--remote-name" or "--remote-component" stops, even if some "--extra-component" are still running. You must specify at least one filter with "--remote-name" or "--remote-component" if you use this option. This option can be specified multiple times.
--fidl-ir-path add the given path as a repository for FIDL IR, in the form of .fidl.json files. Passing a file adds the given file. Passing a directory adds all of the .fidl.json files in that directory and any directory transitively reachable from there. An argfile contains a newline-separated list of .fidl.json files relative to the directory containing the argfile; passing an argfile (starting with the '@' character) adds all files listed in that argfile. This option can be specified multiple times.

limbo

control the process limbo on the target


Usage:  ffx debug limbo [subcommand...]
Options  
--help display usage information
Subcommands  
disable disable the process limbo. Will free any pending processes waiting in it.
enable enable the process limbo. It will now begin to capture crashing processes.
list lists the processes currently waiting on limbo. The limbo must be active.
release release a process from limbo. The limbo must be active.
status query the status of the process limbo.

disable

disable the process limbo. Will free any pending processes waiting in it.


Usage:  ffx debug limbo disable
Options  
--help display usage information

enable

enable the process limbo. It will now begin to capture crashing processes.


Usage:  ffx debug limbo enable
Options  
--help display usage information

list

lists the processes currently waiting on limbo. The limbo must be active.


Usage:  ffx debug limbo list
Options  
--help display usage information

release

release a process from limbo. The limbo must be active.


Usage:  ffx debug limbo release pid
Options  
--help display usage information

status

query the status of the process limbo.


Usage:  ffx debug limbo status
Options  
--help display usage information

symbol-index

manage symbol sources used by other debug commands


Usage:  ffx debug symbol-index [subcommand...]
Options  
--help display usage information
Subcommands  
add add a path or url to the symbol index
clean remove all non-existent paths
list show the content in symbol index
remove remove a path from the symbol index

Notes

  • symbol-index is a global configuration used by debugging tools to locate
symbol files.

add

add a path or url to the symbol index


Usage:  ffx debug symbol-index add [--build-dir <build-dir>] source
Options  
--help display usage information
--build-dir optional build directory used by zxdb to locate the source code

Notes

  • Add a path or a debuginfod server to the symbol index, e.g.,

      

    • A build-id directory, with an optional build directory.
      • 

    • An ids.txt file, with an optional build directory.
      • 

    • A file that ends with .symbol-index.json.
      • 

    • https://debuginfod.debian.net
      •

Duplicated adding of the same path or url is a no-op, regardless of the optional build directory.

clean

remove all non-existent paths


Usage:  ffx debug symbol-index clean
Options  
--help display usage information

Notes

  • Remove all non-existent paths from the symbol index, useful as a garbage
collection.

list

show the content in symbol index


Usage:  ffx debug symbol-index list [-a]
Options  
--help display usage information
-a, --aggregated show the aggregated symbol index

remove

remove a path from the symbol index


Usage:  ffx debug symbol-index remove source
Options  
--help display usage information

Notes

  • Remove a path or a debuginfod server from the symbol index, e.g.,

      

    • A build-id directory.
      • 

    • An ids.txt file.
      • 

    • A file that ends with .symbol-index.json.
      • 

    • https://debuginfod.debian.net

symbolize

symbolize backtraces in markup format


Usage:  ffx debug symbolize [--auth] [--no-prettify] [symbolizer_args...]
Options  
--help display usage information
--auth start the authentication process.
--no-prettify do not prettify the backtraces.

doctor

Run common checks for the ffx tool and host environment


Usage:  ffx doctor [--record] [--no-config] [--retry-count <retry-count>] [--retry-delay <retry-delay>] [--restart-daemon] [-v] [--output-dir <output-dir>] [--repair-keys]
Options  
--help display usage information
--record generates an output zip file with logs
--no-config do not include the ffx configuration file
--retry-count number of times to retry failed connection attempts
--retry-delay timeout delay in ms during connection attempt
--restart-daemon force restart the daemon, even if the connection is working
-v, --verbose verbose, display all steps
--output-dir override the default output directory for doctor records
--repair-keys checks SSH key consistency and repairs them if needed. This may cause any devices to be reflashed.

Examples

To run diagnostics:

    $ ffx doctor

To capture the output and additional logs:

    $ ffx doctor --record

By default, this outputs the zip in the current directory.

To override output dir:

    $ ffx doctor --record --output-dir /tmp/ffx

Notes

  • The doctor subcommand automatically attempts to repair common target
interaction issues and provides useful diagnostic information to the user.

By default, running ffx doctor attempts to establish a connection with the daemon, and restarts the daemon if there is no connection. The default retry_count is '3' and the default 'retry_delay` is '2000' milliseconds.

driver

Support driver development workflows


Usage:  ffx driver [subcommand...]
Options  
--help display usage information
Subcommands  
conformance Download or run driver conformance tests.
debug-bind Allows you to debug bind decisions.
device Performs specified subcommand on device
disable Disables the given driver, and restart its nodes with rematching.
dump Dump device tree
i2c Perform reads and writes on an I2C device
list List drivers
list-composite-node-specs List composite node specs.
list-composites List composites
list-devices List devices
list-hosts List driver hosts and drivers loaded within them
lspci Prints out pci device info
lsusb Print the device tree of the target to stdout
print-input-report Prints input reports and other information of input devices
register Informs the driver manager that a new driver package is available. The driver manager will cache a copy of the driver
restart Restart all driver hosts containing the driver specified by driver_path.
run-tool Runs a driver tool executable in the driver_playground.
static-checks Run static checks against a driver file.
test-node Commands to interact with test nodes.

conformance

Download or run driver conformance tests.


Usage:  ffx driver conformance [subcommand...]
Options  
--help display usage information
Subcommands  
test Runs driver conformance tests.

Examples

To run all tests for a given driver:

$ ffx driver conformance test --driver fuchsia-boot:///#driver/my-driver.cm

To run all tests for a given device:

$ ffx driver conformance test --device sys/platform/pt/PCI0/bus/00:05.0/pt/my-device

To run all tests of a given type(s) for a given driver:

$ ffx driver conformance test --driver fuchsia-boot:///#driver/my-driver.cm --types functional,performance

To run an arbitrary test(s) against a given driver:

$ ffx driver conformance test --driver fuchsia-boot:///#driver/my-driver.cm --tests fuchsia-pkg://fuchsia.com/my-test#meta/my-test.cm

test

Runs driver conformance tests.


Usage:  ffx driver conformance test [--device <device>] [--driver <driver>] [--metadata-path <metadata-path>] [--types <types>] [--categories <categories>] [--tests <tests>] [--cache <cache>] [--x64-package <x64-package>] [--arm64-package <arm64-package>] [--driver-source <driver-source>] [--source-host-type <source-host-type>] [--submission-name <submission-name>] [--version <version>] [--automated-only] [--manual-only] [--preview] [--licenses <licenses>] [--generate-submission] [--package-output-dir <package-output-dir>]
Options  
--help display usage information
--device device topological path. e.g. pci-00:05.0-fidl/my-device
--driver driver libname. e.g. fuchsia-boot:///#driver/my-driver.so
--metadata-path path to FHCP metadata file.
--types WIP. comma-separated list of test types. e.g. performance,functional
--categories comma-separated list of test categories. e.g. imaging::camera,usb
--tests comma-separated list of test components. e.g. fuchsia-pkg://fuchsia.dev/sometest#meta/sometest.cm,fuchsia-pkg://fuchsia.dev/test2#meta/othertest.cm
--cache WIP. local directory storing the resources required for offline testing.
--x64-package path to the x64 driver binary package.
--arm64-package path to the ARM64 driver binary package.
--driver-source driver source URL. (ex. Gerrit link).
--source-host-type host type of the driver source. e.g. gerrit
--submission-name name of the driver submission. Defaults to driver package URL.
--version version number of the driver. Must be a URL-safe format.
--automated-only run only the automated tests.
--manual-only run only the manual tests.
--preview only list the tests that would have been run, but do not run the tests.
--licenses path to the license directory.
--generate-submission generate submission package. To be used for uploading to the Fuchsia Hardware Portal. Defaults to current working directory. Use --package-output-dir to override.
--package-output-dir save submission package package.tar.gz into the given directory. This will implicitly activate --generate-submission.

debug-bind

Allows you to debug bind decisions.


Usage:  ffx driver debug-bind [-p] [-i] [-s] driver_path device_path
Options  
--help display usage information
-p, --print-properties print out the device properties.
-i, --print-instructions print out the bind program instructions.
-s, --select if this exists, the user will be prompted for a component to select.

Examples

To debug why a driver did or didn't bind to a particular device:

    $ driver debug-bind '/boot/driver/usb_video.so' 'sys/platform/pci/00:1f.6'
Errors  
1 Failed to connect to the bind debugger service

device

Performs specified subcommand on device


Usage:  ffx driver device [-s] [subcommand...]
Options  
--help display usage information
-s, --select if this exists, the user will be prompted for a component to select.
Subcommands  
bind Binds the driver specified to the specified device.
rebind Unbinds the driver bound to a device and then attempts to bind a new driver.
unbind Unbinds the driver bound to the specified device.

Examples

To unbind a driver

    $ driver device unbind 'sys/platform/pci:00:01.6'
Errors  
1 Failed to open device

bind

Binds the driver specified to the specified device.


Usage:  ffx driver device bind driver_url_suffix device_path
Options  
--help display usage information

rebind

Unbinds the driver bound to a device and then attempts to bind a new driver.


Usage:  ffx driver device rebind driver_url_suffix device_path
Options  
--help display usage information

unbind

Unbinds the driver bound to the specified device.


Usage:  ffx driver device unbind device_path
Options  
--help display usage information

disable

Disables the given driver, and restart its nodes with rematching.


Usage:  ffx driver disable [-s] url
Options  
--help display usage information
-s, --select if this exists, the user will be prompted for a component to select.

Examples

To disable a driver

    $ driver disable 'fuchsia-pkg://fuchsia.com/example_driver#meta/example_driver.cm'

This can also be used with boot drivers, but keep in mind if the driver being disabled is
critical to the system, the system will become unstable.

    $ driver disable 'fuchsia-boot:///#meta/example_driver.cm'

Notes

  • After this call, nodes that were bound to the requested driver will either have
another driver (specifically a fallback driver) bound to them, or the node becomes an unbound node
ready to bind to a driver later, which is generally done with a register call. If there is a
fallback driver that might take the place of the driver being disabled, and you want to register
your own driver for the node, the fallback driver should be disabled as well.
Errors  
1 Failed to connect to the driver development service

dump

Dump device tree


Usage:  ffx driver dump [-g] [-s] [device]
Options  
--help display usage information
-g, --graph output device graph in dot language so that it may be viewed
-s, --select if this exists, the user will be prompted for a component to select.

Examples

To dump the device tree:

    $ driver dump

To dump the subtree of the device tree under a node:

    $ driver dump my-node-name

To graph device tree:

    $ driver dump --graph | dot -Tpng | display
Errors  
1 Failed to connect to the driver development service

i2c

Perform reads and writes on an I2C device


Usage:  ffx driver i2c [subcommand...]
Options  
--help display usage information
Subcommands  
ping Pings all I2C devices found in /dev/class/i2c/
read Reads a single byte from the address of an I2C device
transact Sends a sequence of I2C transactions to an I2C device in the order they are written
write Writes data to an I2C device

ping

Pings all I2C devices found in /dev/class/i2c/


Usage:  ffx driver i2c ping
Options  
--help display usage information

Examples

Ping all I2C devices found in /dev/class/i2c/:

    $ driver i2cutil ping

read

Reads a single byte from the address of an I2C device


Usage:  ffx driver i2c read device_path [address...]
Options  
--help display usage information

Examples

Read a single byte from the address 0xff04 of the I2C device 000:

    $ driver i2cutil read class/i2c/000 255 4

transact

Sends a sequence of I2C transactions to an I2C device in the order they are written


Usage:  ffx driver i2c transact device_path [transactions...]
Options  
--help display usage information

Examples

Send transactions to read 100 bytes, then write the bytes 0xab, 0x02, and 0xff; and then read 4 bytes to I2C device 004:

    $ driver i2cutil transact r 100 w 171 2 255 r 4

write

Writes data to an I2C device


Usage:  ffx driver i2c write device_path [data...]
Options  
--help display usage information

Examples

Write the bytes 0xab and 0x01 to I2C device 001:

    $ driver i2cutil write class/i2c/001 171 1

list

List drivers


Usage:  ffx driver list [-v] [--loaded] [-s]
Options  
--help display usage information
-v, --verbose list all driver properties
--loaded only list loaded drivers
-s, --select if this exists, the user will be prompted for a component to select.

Examples

To list all drivers with properties:

    $ driver list -v

To list only loaded drivers:

    $ driver list --loaded
Errors  
1 Failed to connect to the driver development service

list-composite-node-specs

List composite node specs.


Usage:  ffx driver list-composite-node-specs [-v] [-n <name>] [-s]
Options  
--help display usage information
-v, --verbose list all driver properties.
-n, --name only show the spec with this name.
-s, --select if this exists, the user will be prompted for a component to select.

Examples

To list all composite node specs with properties:

    $ driver list-composite-node-specs -v

To show a specific composite nod spec, specify a `--name` or `-n` for short:

    $ driver list-composite-node-specs -n example_group
Errors  
1 Failed to connect to the driver development service

list-composites

List composites


Usage:  ffx driver list-composites [-v] [-s]
Options  
--help display usage information
-v, --verbose list all the properties of a composite.
-s, --select if this exists, the user will be prompted for a component to select.

Examples

To list all composites:

    $ driver list-composites -v
Errors  
1 Failed to connect to the driver development service

list-devices

List devices


Usage:  ffx driver list-devices [-s] [-v] [--exact] [--fail-on-missing] [device]
Options  
--help display usage information
-s, --select if this exists, the user will be prompted for a component to select.
-v, --verbose list all device properties.
--exact require an exact match on the device filter, instead of a substring match.
--fail-on-missing return a non-zero exit code if no matching devices are found.

Examples

To list all devices:

    $ driver list-devices -v
Errors  
1 Failed to connect to the driver development service

list-hosts

List driver hosts and drivers loaded within them


Usage:  ffx driver list-hosts [-s]
Options  
--help display usage information
-s, --select if this exists, the user will be prompted for a component to select.

Examples

To list all driver hosts:

    $ driver list-hosts
Errors  
1 Failed to connect to the driver development service

lspci

Prints out pci device info


Usage:  ffx driver lspci [-v] [-q] [-x] [-n] [-N] [-s <filter>] [--select] [service]
Options  
--help display usage information
-v, --verbose print verbose device configuration
-q, --quiet don't print errors found trying to parse the database
-x, --print-config dump raw configuration space
-n, --print-numeric print numeric IDs.
-N, --only-print-numeric only print numeric IDs.
-s, --filter [[]:][slot][.[]] Show only devices in selected slots
--select if this exists, the user will be prompted for a component to select.

Examples

To show the device tree:

    $ driver lspci
Errors  
1 Failed to connect to the device manager service

lsusb

Print the device tree of the target to stdout


Usage:  ffx driver lsusb [-t] [-v] [-c <configuration>] [-d <device>]
Options  
--help display usage information
-t, --tree prints USB device tree
-v, --verbose verbose output (prints descriptors)
-c, --configuration prints configuration descriptor for specified configuration (rather than current configuration)
-d, --device shows only devices with the specified vendor and product ID numbers (in hexadecimal) UsbDevice must be in format vendor[:product]

Examples

To show the device tree:

    $ driver lsusb
Errors  
1 Failed to connect to the device manager service

print-input-report

Prints input reports and other information of input devices


Usage:  ffx driver print-input-report [subcommand...]
Options  
--help display usage information
Subcommands  
descriptor Prints the descriptors of all input devices
feature Prints the features of a given input device
get Gets and prints an input report from an input device
read Prints the input reports of all input devices in real-time

descriptor

Prints the descriptors of all input devices


Usage:  ffx driver print-input-report descriptor [device_path]
Options  
--help display usage information

Examples

Print the descriptors of all input devices:

    $ driver print-input-report descriptor
 
Print the descriptor of input device 001:

    $ driver print-input-report descriptor class/input-report/001

feature

Prints the features of a given input device


Usage:  ffx driver print-input-report feature device_path
Options  
--help display usage information

Examples

Print the features of input device 001:

    $ driver print-input-report feature class/input-report/001

get

Gets and prints an input report from an input device


Usage:  ffx driver print-input-report get device_path device_type
Options  
--help display usage information

Examples

Get and print the touch input report of input device 001:

    $ driver print-input-report get class/input-report/001 touch

read

Prints the input reports of all input devices in real-time


Usage:  ffx driver print-input-report read
Options  
--help display usage information

Examples

Print the input reports of all input devices in real-time:

    $ driver print-input-report read

register

Informs the driver manager that a new driver package is available. The driver manager will cache a copy of the driver


Usage:  ffx driver register [-s] url
Options  
--help display usage information
-s, --select if this exists, the user will be prompted for a component to select.

Examples

To register a driver

    $ driver register 'fuchsia-pkg://fuchsia.com/example_driver#meta/example_driver.cm'
Errors  
1 Failed to connect to the driver registrar service

restart

Restart all driver hosts containing the driver specified by driver_path.


Usage:  ffx driver restart [-s] driver_path
Options  
--help display usage information
-s, --select if this exists, the user will be prompted for a component to select.

Examples

To restart a driver:

    $ driver restart fuchsia-boot:///#driver/e1000.so
Errors  
1 Failed to connect to the driver manager service

run-tool

Runs a driver tool executable in the driver_playground.


Usage:  ffx driver run-tool tool [args...]
Options  
--help display usage information

Examples

To run a tool:

    $ driver run-tool fuchsia-pkg://fuchsiasamples.com/eductl#bin/eductl -- fact 5
Errors  
1 Failed to connect to the driver playground service

static-checks

Run static checks against a driver file.


Usage:  ffx driver static-checks --driver <driver>
Options  
--help display usage information
--driver the path to the driver's FAR file

test-node

Commands to interact with test nodes.


Usage:  ffx driver test-node [-s] [subcommand...]
Options  
--help display usage information
-s, --select if this exists, the user will be prompted for a component to select.
Subcommands  
add Add a test node with a given bind property
remove Remove a test node.

add

Add a test node with a given bind property


Usage:  ffx driver test-node add name property
Options  
--help display usage information

Examples

To add a test node to the driver framework:

    $ driver test-node add my-node my-key-string=my-value-string
Errors  
1 Failed to connect to the driver development service

remove

Remove a test node.


Usage:  ffx driver test-node remove name
Options  
--help display usage information

Examples

To remove a test node to the driver framework:

    $ driver test-node remove my-node
Errors  
1 Failed to connect to the driver development service

echo

run echo test against the daemon


Usage:  ffx echo [text]
Options  
--help display usage information

efi

Manipulate efi partition


Usage:  ffx efi [subcommand...]
Options  
--help display usage information
Subcommands  
create Creates efi partition, copies zircon.bin, bootdata.bin, EFI/BOOT/BOOTX64.EFI, zedboot.bin, etc...

create

Creates efi partition, copies zircon.bin, bootdata.bin, EFI/BOOT/BOOTX64.EFI, zedboot.bin, etc...


Usage:  ffx efi create -o <output> [--zircon <zircon>] [--bootdata <bootdata>] [--efi-bootloader <efi-bootloader>] [--zedboot <zedboot>] [--cmdline <cmdline>]
Options  
--help display usage information
-o, --output target file/disk to write EFI partition to
--zircon optional path to source file for zircon.bin
--bootdata optional path to source file for bootdata.bin
--efi-bootloader optional path to source file for EFI/BOOT/BOOTX64.EFI
--zedboot optional path to a source file for zedboot.bin
--cmdline optional bootloader cmdline file

emu

Start and manage Fuchsia emulators.


Usage:  ffx emu [subcommand...]
Options  
--help display usage information
Subcommands  
console [EXPERIMENTAL] Connect to a running Fuchsia emulator's console.
list List running Fuchsia emulators.
show Show Fuchsia emulator details.
start Start the Fuchsia emulator.
stop Shut down a running Fuchsia emulator.

Notes

  • The emu command is used to start up, manage, and shut down Fuchsia emulators.

The start subcommand launches an emulator according to the configuration in the Product Bundle. Once one or more emulators are running, you can use the list subcommand to see the name and status of all running emulators, and the show subcommand to get a printout of the configuration for a specific emulator. When you're done with an emulator, use the stop subcommand to cleanly terminate that emulator.

For more information on the Fuchsia emulator, see the Getting Started page at https://fuchsia.dev/fuchsia-src/get-started/set_up_femu.

console

[EXPERIMENTAL] Connect to a running Fuchsia emulator's console.


Usage:  ffx emu console [--console-type <console-type>] [-c] [-m] [-s] [name]
Options  
--help display usage information
--console-type selector for which console to attach to. Accepted values are: command machine serial
-c, --command attach to the user-interactive command console. Equivalent to "--console-type command".
-m, --machine attach to the machine-readable command console. Equivalent to "--console-type machine".
-s, --serial attach to the Fuchsia serial console. Equivalent to "--console-type serial".

Examples

ffx emu console -s
ffx emu console fuchsia-emulator --console-type serial

list

List running Fuchsia emulators.


Usage:  ffx emu list [-r]
Options  
--help display usage information
-r, --only-running list only the emulators that are currently in the "running" state.

show

Show Fuchsia emulator details.


Usage:  ffx emu show [--all] [--cmd] [--config] [--device] [--net] [name]
Options  
--help display usage information
--all show all of the available details, which is the default.
--cmd show the command line used to launch the emulator.
--config show the configuration in a format consistent with the 'start' command's --config flag.
--device show the virtual device information used to launch this emulator, in a format consistent with the 'start' command's --device flag.
--net switch to show network details.

start

Start the Fuchsia emulator.


Usage:  ffx emu start [--accel <accel>] [--config <config>] [--dev-config <dev-config>] [--console] [--debugger] [--device <device>] [--device-list] [--dry-run] [--edit] [--engine <engine>] [--gpu <gpu>] [-H] [--hidpi-scaling <hidpi-scaling>] [-c <kernel-args...>] [-l <log>] [-m] [--name <name>] [--net <net>] [--port-map <port-map...>] [--reuse] [--reuse-with-check] [--stage] [-s <startup-timeout>] [--uefi] [--vbmeta-key <vbmeta-key>] [--vbmeta-key-metadata <vbmeta-key-metadata>] [-V] [product_bundle]
Options  
--help display usage information
--accel virtualization acceleration. Valid choices are "none" to disable acceleration, "hyper" to use the host's hypervisor interface (KVM on Linux and HVF on MacOS), or "auto" to use the hypervisor if detected. The default value is "auto".
--config specify a configuration file to populate the command line flags for the emulator. Defaults to a Handlebars config specified in the Product Bundle manifest.
--dev-config specify developer config file to append onto the configuration. This is a JSON file with the object structure: {{ "args": [], "kernel_args": [], "env" : {{"key": "value"}} }}
--console launch the emulator in serial console mode. This redirects the virtual serial port to the host's input/output streams, multi-plexed with the QEMU monitor console, then maintains a connection to those streams rather than returning control to the host terminal. This is especially useful when the guest is running without networking enabled. Note: Control sequences are passed through to the guest system in this mode, so Crtl-c will terminate the guest system's shell, rather than the emulator process itself. If you need to hard-kill the emulator, use the QEMU sequence 'Ctrl-a x' instead.
--debugger pause on launch and wait for a debugger process to attach before resuming. The guest operating system will not begin execution until a debugger, such as gdb or lldb, attaches to the emulator process and signals the emulator to continue.
--device the virtual device specification used to configure the emulator. This can be the name of a device listed in the product bundle, or the path to a custom virtual device file. A default for this flag can be set by running ffx config set emu.device <type>. If --device is not specified and no default is set, then ffx emu will attempt to use the first device listed in the PBM(v1), or the product bundle's recommended device(v2).
--device-list print the list of available virtual devices.
--dry-run sets up the emulation configuration, but doesn't stage files or start the emulator. The command line arguments that the current configuration generates will be printed to stdout for review.
--edit open the user's default editor to modify the command line flags for the emulator.
--engine emulation engine to use for this instance. Allowed values are "femu" which is based on Android Emulator, and "qemu" which uses the version of Qemu packaged with Fuchsia. Default is "femu". This can be overridden by running ffx config set emu.engine <type>.
--gpu GPU acceleration mode. Allowed values are "swiftshader_indirect", "host", or "auto". Default is "swiftshader_indirect". "host" and "auto" are for experimental use only and are not officially supported by the Fuchsia emulator team; graphics artifacts, test failures and emulator crashes may occur. Note: this is unused when using the "qemu" engine type. See https://developer.android.com/studio/run/emulator-acceleration#command-gpu for details on the available options. This can be overridden by running ffx config set emu.gpu <type>.
-H, --headless run the emulator without a GUI. The guest system may still initialize graphics drivers, but no graphics interface will be presented to the user.
--hidpi-scaling enable pixel scaling on HiDPI devices. Defaults to true for MacOS, false otherwise.
-c, --kernel-args passes the given string to the emulator executable, appended after all other arguments (since duplicated values favor the later value). This means command-line values will override configuration-provided values for any of these kernel arguments. Can be repeated arbitrarily many times for multiple additional kernel arguments.
-l, --log store the emulator log at the provided filesystem path. By default, all output goes to a log file in the emulator working directory. The path to this file is printed onscreen during start-up.
-m, --monitor launch the emulator in Qemu monitor console mode. See https://qemu-project.gitlab.io/qemu/system/monitor.html for more information on the Qemu monitor console.
--name name of this emulator instance. This is used to identify the instance in other commands and tools. Default is "fuchsia-emulator". This value can also be set via configuration using the key emu.name. Note that when using the --uefi flag, the visible target name in ffx target list will be overwritten by a name "fuchsia-X-Y-Z" where X,Y,Z are derived from the generated mac address for this emulator. This is currently required to support a seamless OTA testing workflow.
--net specify the networking mode for the emulator. Allowed values are "none" which disables networking, "tap" which attaches to a Tun/Tap interface, "user" which sets up mapped ports via SLiRP, and "auto" which will check the host system's capabilities and select "tap" if it is available and "user" otherwise. Default is "auto". This can be overridden by running ffx config set emu.net <type>.
--port-map specify a host port mapping for user-networking mode. Ignored in other networking modes. Syntax is "--port-map :". The must be one of those specified in the virtual device specification. This flag may be repeated for multiple port mappings.
--reuse reuse a persistent emulator's (i.e. stopped with ffx emu stop --persist) state when starting up. If an emulator with the same name as this instance has been previously started and then stopped without cleanup, this instance will reuse the images from the previous instance. If no previous instance is found, or if the old instance is still running, the new emulator will not attempt to start.
--reuse-with-check reuse a persistent emulator's (i.e. stopped with ffx emu stop --persist) state when starting up after version check. If an emulator with the same name as this instance has been previously started and then stopped without cleanup, the zbi and disk volume files are compared against the original. If they match, the instance will reuse the images from the previous instance. If the files do not match, the instance is started using the latest files. If there is no staged instance, the emulator is started using the latest files and the hash information is recorded so this instance can take advantage of this option.
--stage sets up the emulation configuration and stages files, but doesn't start the emulator. The command line arguments that the staged configuration generates will be printed to stdout for review.
-s, --startup-timeout the maximum time (in seconds) to wait on an emulator to boot before returning control to the user. A value of 0 will skip the check entirely. Default is 60 seconds. This can be overridden with ffx config set emu.start.timeout <seconds>.
--uefi create and start an emulator with a full GPT disk including UEFI boot environment and all partitions in one flat file. This approximates a physical device as closely as possible. Note that this is currently only enabled for x64 and arm64 targets. RISC-V is unsupported. Note that for full GPT disks, it is also required to provide the --vbmeta-key and --vbmeta-key-metadata arguments, otherwise the resulting GPT image will not be able to boot into its A and B slots.
--vbmeta-key path to the key (a PEM file) that should be used to sign a vbmeta file for the ZBI after embedding the SSH keys, for example: https://cs.opensource.google/fuchsia/fuchsia/+/main:boards/x64/BUILD.gn;l=44-46;drc=04892e7f8875e2d16c3fcda89bc462dc6b0f35f8) Note that this is only required when using --uefi. Also, when an emulator is --reused after it was stopped with the --persist flag, this argument is not necessary as the previously created images will be used.
--vbmeta-key-metadata path to the key metadata (a binary file accompanying the PEM, for example https://cs.opensource.google/fuchsia/fuchsia/+/main:boards/x64/BUILD.gn;l=44-46;drc=04892e7f8875e2d16c3fcda89bc462dc6b0f35f8) that should be used to sign a vbmeta file for the ZBI after embedding the SSH keys. Note that this is only required when using --uefi. Also, when an emulator is --reused after it was stopped with the --persist flag, this argument is not necessary as the
-V, --verbose enables extra logging for debugging.

Examples

ffx emu start

Notes

  • The start subcommand is the starting point for all emulator interactions.
The name provided here will be used for all later interactions to indicate
which emulator to target. Emulator names must be unique.

The start command will compile all of the necessary configuration for an emulator, launch the emulator, and then store the configuration on disk for future reference. The configuration comes from the Product Bundle, which includes a virtual device specification and a start-up flag template. See https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0100_product_metadata for more information.

stop

Shut down a running Fuchsia emulator.


Usage:  ffx emu stop [--all] [-p] [name]
Options  
--help display usage information
--all shut down and clean up all emulator instances running on the device.
-p, --persist don't remove the state directory on stop, just terminate the emulator.

Examples

ffx emu stop
ffx emu stop --all
ffx emu stop fuchsia-emulator --persist

Notes

  • By default, the stop command will remove an emulator's on-disk
working directory, which contains emulator state, staged image files, etc.

Use the --persist flag if you need to leave the working directory intact while shutting down the emulator, for debugging or troubleshooting purposes. The working directory will be left in place, and the emulator will be marked [Inactive] in ffx emu list results until stop is called for that instance without the --persist flag.

fuzz

Start and manage fuzzers.


Usage:  ffx fuzz [subcommand...]
Options  
--help display usage information
Subcommands  
add Adds an input to a fuzzer's corpus.
cleanse Clears extraneous bytes from an error input.
fetch Retrieves the attached fuzzer's corpus.
get Gets option(s) from a fuzzer.
list Lists available fuzzers.
merge Compacts the attached fuzzer's corpus.
minimize Reduce the size of an error input.
run Generates inputs and fuzz the target.
set Sets options on a fuzzer.
shell Starts an interactive fuzzing session.
status Gets a fuzzer's execution status.
stop Stops a fuzzer.
try Tests a specific input with a fuzzer.

add

Adds an input to a fuzzer's corpus.


Usage:  ffx fuzz add [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] [-s] url input
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer
-s, --seed add to the seed corpus; default is to add to live corpus

cleanse

Clears extraneous bytes from an error input.


Usage:  ffx fuzz cleanse [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url input
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer

fetch

Retrieves the attached fuzzer's corpus.


Usage:  ffx fuzz fetch [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] [-s] url
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer
-s, --seed fetch the seed corpus; default is to fetch the live corpus

get

Gets option(s) from a fuzzer.


Usage:  ffx fuzz get [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url [name]
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer

list

Lists available fuzzers.


Usage:  ffx fuzz list [-j <json-file>] [-p <pattern>]
Options  
--help display usage information
-j, --json-file path to JSON file describing fuzzers; looks for tests.json under $FUCHSIA_DIR by default
-p, --pattern list all fuzzers matching shell-style glob pattern; default is to list all fuzzers

merge

Compacts the attached fuzzer's corpus.


Usage:  ffx fuzz merge [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer

minimize

Reduce the size of an error input.


Usage:  ffx fuzz minimize [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] [-r <runs>] [-t <time>] url input
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer
-r, --runs convenient shortcut for "set runs "
-t, --time convenient shortcut for "set max_total_time "

run

Generates inputs and fuzz the target.


Usage:  ffx fuzz run [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] [-r <runs>] [-t <time>] url
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer
-r, --runs convenient shortcut for "set runs "
-t, --time convenient shortcut for "set max_total_time "

set

Sets options on a fuzzer.


Usage:  ffx fuzz set [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url name value
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer

shell

Starts an interactive fuzzing session.


Usage:  ffx fuzz shell [-j <json-file>]
Options  
--help display usage information
-j, --json-file path to JSON file describing fuzzers; looks for tests.json under $FUCHSIA_DIR by default

status

Gets a fuzzer's execution status.


Usage:  ffx fuzz status [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer

stop

Stops a fuzzer.


Usage:  ffx fuzz stop [-q] [url]
Options  
--help display usage information
-q, --quiet if present, suppress non-error output from the ffx tool itself

try

Tests a specific input with a fuzzer.


Usage:  ffx fuzz try [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url input
Options  
--help display usage information
-o, --output where to send fuzzer logs and artifacts; default is stdout and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool itself
--no-stdout disables forwarding standard output from the fuzzer
--no-stderr disables forwarding standard error from the fuzzer
--no-syslog disables forwarding system logs from the fuzzer

inspect

Query data exposed by components via the Inspect API.


Usage:  ffx inspect [subcommand...]
Options  
--help display usage information
Subcommands  
apply-selectors Apply selectors from a file interactively.
list Lists all components (relative to the scope where the archivist receives events from) of components that expose inspect.
list-accessors Lists all available ArchiveAccessor in the system and their selector for use in "accessor" arguments in other sub-commands.
selectors Lists all available selectors for the given input of component queries or partial selectors.
show Prints the inspect hierarchies that match the given selectors. See https://fuchsia.dev/fuchsia-src/development/diagnostics/inspect#userspace_tools for more.

Examples

If you wish to see the JSON format of Inspect, you must pass `--machine json` to the `ffx` command. 
For example to see the Inspect JSON of all components running in the system, run: 

```
ffx --machine json inspect show
```

apply-selectors

Apply selectors from a file interactively.


Usage:  ffx inspect apply-selectors [--snapshot-file <snapshot-file>] [--moniker <moniker>] [--accessor-path <accessor-path>] selector_file
Options  
--help display usage information
--snapshot-file path to the inspect json file to read this file contains inspect.json data from snapshot.zip. If not provided, DiagnosticsProvider will be used to get inspect data.
--moniker moniker of the component to apply the command.
--accessor-path the path from where to get the ArchiveAccessor connection. If the given path is a directory, the command will look for a fuchsia.diagnostics.ArchiveAccessor service file. If the given path is a service file, the command will attempt to connect to it as an ArchiveAccessor.

list

Lists all components (relative to the scope where the archivist receives events from) of components that expose inspect.


Usage:  ffx inspect list [--component <component>] [--with-url] [--accessor <accessor>]
Options  
--help display usage information
--component a fuzzy-search query. May include URL, moniker, or manifest fragments. a fauzzy-search query for the component we are interested in. May include URL, moniker, or manifest fragments. If this is provided, the output will only contain monikers for components that matched the query.
--with-url also print the URL of the component.
--accessor A selector specifying what fuchsia.diagnostics.ArchiveAccessor to connect to. The selector will be in the form of: :fuchsia.diagnostics.ArchiveAccessor(.pipeline_name)? Typically this is the output of iquery list-accessors. For example: bootstrap/archivist:fuchsia.diagnostics.ArchiveAccessor.feedback means that the command will connect to the ArchiveAccecssor filtered by the feedback pipeline exposed by bootstrap/archivist.

list-accessors

Lists all available ArchiveAccessor in the system and their selector for use in "accessor" arguments in other sub-commands.


Usage:  ffx inspect list-accessors
Options  
--help display usage information

selectors

Lists all available selectors for the given input of component queries or partial selectors.


Usage:  ffx inspect selectors [--component <component>] [--accessor <accessor>] [selectors...]
Options  
--help display usage information
--component a fuzzy-search query. May include URL, moniker, or manifest fragments. No selector-escaping for moniker is needed in this query. Selectors following --component should omit the component selector, as they will be spliced together by the tool with the correct escaping.
--accessor A string specifying what fuchsia.diagnostics.ArchiveAccessor to connect to. This can be copied from the output of ffx inspect list-accessors. The selector will be in the form of: :fuchsia.diagnostics.ArchiveAccessor.pipeline_name

show

Prints the inspect hierarchies that match the given selectors. See https://fuchsia.dev/fuchsia-src/development/diagnostics/inspect#userspace_tools for more.


Usage:  ffx inspect show [--component <component>] [--accessor <accessor>] [--name <name>] [selectors...]
Options  
--help display usage information
--component a fuzzy-search query. May include URL, moniker, or manifest fragments. No selector-escaping for moniker is needed in this query. Selectors following --component should omit the component selector, as they will be spliced together by the tool with the correct escaping.
--accessor A string specifying what fuchsia.diagnostics.ArchiveAccessor to connect to. This can be copied from the output of ffx inspect list-accessors. The selector will be in the form of: :fuchsia.diagnostics.ArchiveAccessorName
--name specifies a tree published by a component by name. If a selector is also provided, the specified name will be added to the selector.

log

Display logs from a target device


Usage:  ffx log [--filter <filter...>] [--moniker <moniker...>] [--component <component...>] [--exclude <exclude...>] [--tag <tag...>] [--exclude-tags <exclude-tags...>] [--severity <severity>] [--kernel] [--since <since>] [--since-boot <since-boot>] [--until <until>] [--until-boot <until-boot>] [--hide-tags] [--hide-file] [--no-color] [--show-metadata] [--show-full-moniker] [--clock <clock>] [--symbolize <symbolize>] [--set-severity <set-severity...>] [--pid <pid>] [--tid <tid>] [--force-set-severity] [subcommand...]
Options  
--help display usage information
--filter filter for a string in either the message, component or url. May be repeated.
--moniker DEPRECATED: use --component
--component fuzzy search for a component by moniker or url. May be repeated.
--exclude exclude a string in either the message, component or url. May be repeated.
--tag filter for only logs with a given tag. May be repeated.
--exclude-tags exclude logs with a given tag. May be repeated.
--severity set the minimum severity. Accepted values (from lower to higher) are: trace, debug, info, warn (or warning), error, fatal. This field is case insensitive.
--kernel outputs only kernel logs, unless combined with --component.
--since show only logs after a certain time (exclusive)
--since-boot show only logs after a certain time (as a boot timestamp: seconds from the target's boot time).
--until show only logs until a certain time (exclusive)
--until-boot show only logs until a certain time (as a a boot timestamp: seconds since the target's boot time).
--hide-tags hide the tag field from output (does not exclude any log messages)
--hide-file hide the file and line number field from output (does not exclude any log messages)
--no-color disable coloring logs according to severity. Note that you can permanently disable this with ffx config set log_cmd.color false
--show-metadata shows process-id and thread-id in log output
--show-full-moniker shows the full moniker in log output. By default this is false and only the last segment of the moniker is printed.
--clock how to display log timestamps. Options are "utc", "local", or "boot" (i.e. nanos since target boot). Default is boot.
--symbolize configure symbolization options. Valid options are: - pretty (default): pretty concise symbolization - off: disables all symbolization - classic: traditional, non-prettified symbolization
--set-severity configure the log settings on the target device for components matching the given selector. This modifies the minimum log severity level emitted by components during the logging session. Specify using the format #, with level as one of FATAL
--pid filters by pid
--tid filters by tid
--force-set-severity if enabled, selectors will be passed directly to Archivist without any filtering. If disabled and no matching components are found, the user will be prompted to either enable this or be given a list of selectors to choose from.
Subcommands  
dump Dumps all log from a given target's session.
watch Watches for and prints logs from a target. Default if no sub-command is specified.

Examples

Dump the most recent logs and stream new ones as they happen:
  $ ffx log

Stream new logs starting from the current time, filtering for severity of at least "WARN":
  $ ffx log --severity warn --since now

Stream logs where the source moniker, component url and message do not include "sys":
  $ ffx log --exclude sys

Stream ERROR logs with source moniker, component url or message containing either
"netstack" or "remote-control.cm", but not containing "sys":
  $ ffx log --severity error --filter netstack --filter remote-control.cm --exclude sys

Dump all available logs where the source moniker, component url, or message contains
"remote-control":
  $ ffx log --filter remote-control dump

Dump all logs from the last 30 minutes logged before 5 minutes ago:
  $ ffx log --since "30m ago" --until "5m ago" dump

Enable DEBUG logs from the "core/audio" component while logs are streaming:
  $ ffx log --set-severity core/audio#DEBUG

Notes

  • Logs are retrieve from the target at the moment this command is called.

You may see some additional information attached to the log line:

  • dropped=N: this means that N logs attributed to the component were dropped when the component wrote to the log socket. This can happen when archivist cannot keep up with the rate of logs being emitted by the component and the component filled the log socket buffer in the kernel.

  • rolled=N: this means that N logs rolled out from the archivist buffer and ffx never saw them. This can happen when more logs are being ingested by the archivist across all components and the ffx couldn't retrieve them fast enough.

Symbolization is performed in the background using the symbolizer host tool. You can pass additional arguments to the symbolizer tool (for example, to add a remote symbol server) using: $ ffx config set proactive_log.symbolize.extra_args "--symbol-server gs://some-url/path --symbol-server gs://some-other-url/path ..."

To learn more about configuring the log viewer, visit https://fuchsia.dev/fuchsia-src/development/tools/ffx/commands/log

dump

Dumps all log from a given target's session.


Usage:  ffx log dump
Options  
--help display usage information

watch

Watches for and prints logs from a target. Default if no sub-command is specified.


Usage:  ffx log watch
Options  
--help display usage information

net

View and manage target network configuration


Usage:  ffx net [--realm <realm>] [subcommand...]
Options  
--help display usage information
--realm a realm to target when sending commands. Defaults to the core network realm.
Subcommands  
dhcp commands for an interfaces dhcp client
dhcpd commands to control a dhcp server
dns commands to control the dns resolver
filter commands for configuring packet filtering
filter-deprecated commands for configuring packet filtering with the deprecated API
if commands for network interfaces
log commands for logging
migration controls netstack selection for migration from netstack2 to netstack3
neigh commands for neighbor tables
route commands for routing tables
rule commands for policy-based-routing rules

dhcp

commands for an interfaces dhcp client


Usage:  ffx net dhcp [subcommand...]
Options  
--help display usage information
Subcommands  
start starts a dhcp client on the interface
stop stops the dhcp client on the interface

start

starts a dhcp client on the interface


Usage:  ffx net dhcp start nicid or name:ifname
Options  
--help display usage information

stop

stops the dhcp client on the interface


Usage:  ffx net dhcp stop nicid or name:ifname
Options  
--help display usage information

dhcpd

commands to control a dhcp server


Usage:  ffx net dhcpd [subcommand...]
Options  
--help display usage information
Subcommands  
clear-leases A primary command to clear the leases maintained by dhcpd.
get A primary command to retrieve the value of a DHCP option or server parameter.
list A primary command to list the values of all DHCP options or server parameters.
reset A primary command to reset the values of all DHCP options or server parameters.
set A primary command to set the value of a DHCP option or server parameter.
start A primary command to start the DHCP server.
stop A primary command to stop the DHCP server.

clear-leases

A primary command to clear the leases maintained by dhcpd.


Usage:  ffx net dhcpd clear-leases
Options  
--help display usage information

get

A primary command to retrieve the value of a DHCP option or server parameter.


Usage:  ffx net dhcpd get [subcommand...]
Options  
--help display usage information
Subcommands  
option A secondary command indicating a DHCP option argument.
parameter A secondary command indicating a server parameter argument.
option

A secondary command indicating a DHCP option argument.


Usage:  ffx net dhcpd get option [subcommand...]
Options  
--help display usage information
Subcommands  
all-subnets-local Flag indicating if all subnets of the connected network have the same MTU.
arp-cache-timeout Timeout for ARP cache entries.
boot-file-size Size of the default boot image for the client.
bootfile-name Bootfile name for the client.
broadcast-address Broadcast address of the client's subnet.
cookie-server RFC 865 Cookie servers available to the client.
default-finger-server Default Finger servers available to the client.
default-ip-ttl Default time-to-live to use on outgoing IP datagrams.
default-irc-server Default IRC servers available to the client.
default-www-server Default WWW servers available to the client.
domain-name Domain name of the client.
domain-name-server Domain Name System servers available to the client.
ethernet-encapsulation Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation.
extensions-path Path name to a TFTP-retrievable file containing vendor-extension information.
host-name Name of the client.
impress-server Imagen Impress servers available to the client.
interface-mtu MTU for the client's interface.
ip-forwarding Flag enabling/disabling IP layer packet forwarding.
log-server MIT-LCS UDP Log servers available to the client.
lpr-server RFC 1179 Line Printer servers available to the client.
mask-supplier Flag indicating whether the client should respond to subnet mask discovery requests via ICMP.
max-datagram-reassembly-size Maximum sized datagram that the client should be able to reassemble.
max-message-size Maximum length of a DHCP message that the participant is willing to accept.
merit-dump-file Path name of a core dump file.
mobile-ip-home-agent Mobile IP home agents available to the client.
name-server IEN 116 Name servers available to the client.
net-bios-over-tcpip-distribution-server NetBIOS datagram distribution servers available to the client.
net-bios-over-tcpip-name-server NetBIOS name servers available to the client.
net-bios-over-tcpip-node-type The NetBIOS node type which should be used by the client.
net-bios-over-tcpip-scope NetBIOS scope parameter for the client.
network-information-servers Network Information Service servers available to the client.
network-information-service-domain Name of the client's Network Information Service domain.
network-information-service-plus-domain Network Information System+ domain name.
network-information-service-plus-servers Network Information System+ servers available to the client.
network-time-protocol-servers Network Time Protocol servers available to the client.
nntp-server NNTP servers available to the client.
non-local-source-routing Flag enabling/disabling forwarding of IP packets with non-local source routes.
path-mtu-aging-timeout Timeout to use when aging Path MTU values.
path-mtu-plateau-table Table of MTU sizes for Path MTU Discovery.
perform-mask-discovery Flag indicating whether the client should perform subnet mask discovery via ICMP.
perform-router-discovery Flag indicating whether the client should solicit routers using Router Discovery.
policy-filter Policy filters for non-local source routing.
pop3-server POP3 servers available to the client.
rebinding-time-value Time interval from address assignment at which the client transitions to a Rebinding state.
renewal-time-value Time interval from address assignment at which the client transitions to a Renewing state.
resource-location-server RFC 887 Resource Location servers available to the client.
root-path Path name to a TFTP-retrievable file containing vendor-extension information.
router The routers within a client's subnet.
router-solicitation-address Destination address for Router Solicitation requests.
smtp-server SMTP servers available to the client.
static-route Static Routes which the client should put in its routing cache.
stda-server StreetTalk Directory Assistance servers available to the client.
street-talk-server StreetTalk servers available to the client.
subnet-mask The client's subnet mask.
swap-server Address of the client's swap server.
tcp-default-ttl Default time-to-live for outgoing TCP segments.
tcp-keepalive-garbage Flag specifying whether the client should send TCP keepalive messages with an octet of garbage.
tcp-keepalive-interval Interval the client should wait before sending a TCP keepalive message.
tftp-server-name TFTP server available to the client.
time-offset The client's offset from UTC.
time-server Time Protocol servers available to the client.
trailer-encapsulation Flag specifying whether the client should negotiate the use of trailers in ARP.
vendor-specific-information Option for exchanging vendor-specific information between the DHCP client and DHCP server.
x-window-system-display-manager X window System Display Manager systems available to the client.
x-window-system-font-server X Window System Font servers available to the client.
all-subnets-local

Flag indicating if all subnets of the connected network have the same MTU.


Usage:  ffx net dhcpd get option all-subnets-local [--local]
Options  
--help display usage information
--local a flag indicating if all subents of the IP network to which the client is connected have the same MTU.
arp-cache-timeout

Timeout for ARP cache entries.


Usage:  ffx net dhcpd get option arp-cache-timeout [--timeout <timeout>]
Options  
--help display usage information
--timeout the timeout for ARP cache entries, in seconds.
boot-file-size

Size of the default boot image for the client.


Usage:  ffx net dhcpd get option boot-file-size [--size <size>]
Options  
--help display usage information
--size the size of the client's default boot image in 512-octet blocks.
bootfile-name

Bootfile name for the client.


Usage:  ffx net dhcpd get option bootfile-name [--name <name>]
Options  
--help display usage information
--name the bootfile name for the client. This option should be used when the file field has been overloaded to carry options.
broadcast-address

Broadcast address of the client's subnet.


Usage:  ffx net dhcpd get option broadcast-address [--addr <addr>]
Options  
--help display usage information
--addr the broadcast address of the client's subnet. Legal values are defined in RFC 1122.

RFC 865 Cookie servers available to the client.


Usage:  ffx net dhcpd get option cookie-server [--cookie-servers <cookie-servers...>]
Options  
--help display usage information
--cookie-servers a list of RFC 865 Cookie servers available to the client, in order of preference.
default-finger-server

Default Finger servers available to the client.


Usage:  ffx net dhcpd get option default-finger-server [--finger-servers <finger-servers...>]
Options  
--help display usage information
--finger-servers a list of default Finger server addresses available to the client, listed in order of preference.
default-ip-ttl

Default time-to-live to use on outgoing IP datagrams.


Usage:  ffx net dhcpd get option default-ip-ttl [--ttl <ttl>]
Options  
--help display usage information
--ttl the default time-to-live to use on outgoing IP datagrams. The value must be between 1 and 255.
default-irc-server

Default IRC servers available to the client.


Usage:  ffx net dhcpd get option default-irc-server [--irc-servers <irc-servers...>]
Options  
--help display usage information
--irc-servers a list of Internet Relay Chat server addresses available to the client, listed in order of preference.
default-www-server

Default WWW servers available to the client.


Usage:  ffx net dhcpd get option default-www-server [--www-servers <www-servers...>]
Options  
--help display usage information
--www-servers a list of default World Wide Web (WWW) server addresses available to the client, listed in order of preference.
domain-name

Domain name of the client.


Usage:  ffx net dhcpd get option domain-name [--name <name>]
Options  
--help display usage information
--name the client's domain name for use in resolving hostnames in the DNS.
domain-name-server

Domain Name System servers available to the client.


Usage:  ffx net dhcpd get option domain-name-server [--domain-name-servers <domain-name-servers...>]
Options  
--help display usage information
--domain-name-servers a list of DNS servers available to the client, in order of preference;
ethernet-encapsulation

Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation.


Usage:  ffx net dhcpd get option ethernet-encapsulation [--encapsulate]
Options  
--help display usage information
--encapsulate a flag specifying that the client should use Ethernet v2 encapsulation when false, and IEEE 802.3 encapsulation when true.
extensions-path

Path name to a TFTP-retrievable file containing vendor-extension information.


Usage:  ffx net dhcpd get option extensions-path [--path <path>]
Options  
--help display usage information
--path the path name to a TFTP-retrievable file. This file contains data which can be interpreted as the BOOTP vendor-extension field. Unlike the BOOTP vendor-extension field, this file has an unconstrained length and any references to Tag 18 are ignored.
host-name

Name of the client.


Usage:  ffx net dhcpd get option host-name [--name <name>]
Options  
--help display usage information
--name the name of client, which may or may not be qualified with the local domain name.
impress-server

Imagen Impress servers available to the client.


Usage:  ffx net dhcpd get option impress-server [--impress-servers <impress-servers...>]
Options  
--help display usage information
--impress-servers a list of Imagen Impress servers available to the client, in order of preference.
interface-mtu

MTU for the client's interface.


Usage:  ffx net dhcpd get option interface-mtu [--mtu <mtu>]
Options  
--help display usage information
--mtu the MTU for the client's interface. Minimum value of 68.
ip-forwarding

Flag enabling/disabling IP layer packet forwarding.


Usage:  ffx net dhcpd get option ip-forwarding [--enabled]
Options  
--help display usage information
--enabled a flag which will enabled IP layer packet forwarding when true.
log-server

MIT-LCS UDP Log servers available to the client.


Usage:  ffx net dhcpd get option log-server [--log-servers <log-servers...>]
Options  
--help display usage information
--log-servers a list of MIT-LCS UDP Log servers available to the client, in order of preference.
lpr-server

RFC 1179 Line Printer servers available to the client.


Usage:  ffx net dhcpd get option lpr-server [--lpr-servers <lpr-servers...>]
Options  
--help display usage information
--lpr-servers a list of RFC 1179 Line Printer servers available to the client, in order of preference.
mask-supplier

Flag indicating whether the client should respond to subnet mask discovery requests via ICMP.


Usage:  ffx net dhcpd get option mask-supplier [--supplier]
Options  
--help display usage information
--supplier a flag indicating whether the client should respond to subnet mask discovery requests via ICMP.
max-datagram-reassembly-size

Maximum sized datagram that the client should be able to reassemble.


Usage:  ffx net dhcpd get option max-datagram-reassembly-size [--size <size>]
Options  
--help display usage information
--size the maximum sized datagram that the client should be able to reassemble, in octets. The minimum legal value is 576.
max-message-size

Maximum length of a DHCP message that the participant is willing to accept.


Usage:  ffx net dhcpd get option max-message-size [--length <length>]
Options  
--help display usage information
--length the maximum length in octets of a DHCP message that the participant is willing to accept. The minimum value is 576.
merit-dump-file

Path name of a core dump file.


Usage:  ffx net dhcpd get option merit-dump-file [--path <path>]
Options  
--help display usage information
--path the path name to the client's core dump in the event the client crashes.
mobile-ip-home-agent

Mobile IP home agents available to the client.


Usage:  ffx net dhcpd get option mobile-ip-home-agent [--home-agents <home-agents...>]
Options  
--help display usage information
--home-agents a list of mobile IP home agent addresses available to the client, listed in order of preference.
name-server

IEN 116 Name servers available to the client.


Usage:  ffx net dhcpd get option name-server [--name-servers <name-servers...>]
Options  
--help display usage information
--name-servers a list of IEN 116 Name servers available to the client, in order of preference.
net-bios-over-tcpip-distribution-server

NetBIOS datagram distribution servers available to the client.


Usage:  ffx net dhcpd get option net-bios-over-tcpip-distribution-server [--servers <servers...>]
Options  
--help display usage information
--servers a list of NetBIOS datagram distribution servers available to the client, listed in order of preference.
net-bios-over-tcpip-name-server

NetBIOS name servers available to the client.


Usage:  ffx net dhcpd get option net-bios-over-tcpip-name-server [--servers <servers...>]
Options  
--help display usage information
--servers a list of NetBIOS name server addresses available to the client, listed in order of preference.
net-bios-over-tcpip-node-type

The NetBIOS node type which should be used by the client.


Usage:  ffx net dhcpd get option net-bios-over-tcpip-node-type [subcommand...]
Options  
--help display usage information
Subcommands  
b-node A B node type.
h-node A H node type.
m-node A M node type.
p-node A P node type.
# b-node

A B node type.


Usage:  ffx net dhcpd get option net-bios-over-tcpip-node-type b-node
Options  
--help display usage information
# h-node

A H node type.


Usage:  ffx net dhcpd get option net-bios-over-tcpip-node-type h-node
Options  
--help display usage information
# m-node

A M node type.


Usage:  ffx net dhcpd get option net-bios-over-tcpip-node-type m-node
Options  
--help display usage information
# p-node

A P node type.


Usage:  ffx net dhcpd get option net-bios-over-tcpip-node-type p-node
Options  
--help display usage information
net-bios-over-tcpip-scope

NetBIOS scope parameter for the client.


Usage:  ffx net dhcpd get option net-bios-over-tcpip-scope [--scope <scope>]
Options  
--help display usage information
--scope the NetBIOS over TCP/IP scope parameter, as defined in RFC 1001, for the client.
network-information-servers

Network Information Service servers available to the client.


Usage:  ffx net dhcpd get option network-information-servers [--servers <servers...>]
Options  
--help display usage information
--servers a list of Network Information Service server addresses available to the client, listed in order of preference.
network-information-service-domain

Name of the client's Network Information Service domain.


Usage:  ffx net dhcpd get option network-information-service-domain [--domain-name <domain-name>]
Options  
--help display usage information
--domain-name the name of the client's Network Information Service domain.
network-information-service-plus-domain

Network Information System+ domain name.


Usage:  ffx net dhcpd get option network-information-service-plus-domain [--domain-name <domain-name>]
Options  
--help display usage information
--domain-name the name of the client's Network Information System+ domain.
network-information-service-plus-servers

Network Information System+ servers available to the client.


Usage:  ffx net dhcpd get option network-information-service-plus-servers [--servers <servers...>]
Options  
--help display usage information
--servers a list of Network Information System+ server addresses available to the client, listed in order of preference.
network-time-protocol-servers

Network Time Protocol servers available to the client.


Usage:  ffx net dhcpd get option network-time-protocol-servers [--servers <servers...>]
Options  
--help display usage information
--servers a list of Network Time Protocol (NTP) server addresses available to the client, listed in order of preference.
nntp-server

NNTP servers available to the client.


Usage:  ffx net dhcpd get option nntp-server [--nntp-servers <nntp-servers...>]
Options  
--help display usage information
--nntp-servers a list Network News Transport Protocol (NNTP) server addresses available to the client, listed in order of preference.
non-local-source-routing

Flag enabling/disabling forwarding of IP packets with non-local source routes.


Usage:  ffx net dhcpd get option non-local-source-routing [--enabled]
Options  
--help display usage information
--enabled a flag which will enable forwarding of IP packets with non-local source routes.
path-mtu-aging-timeout

Timeout to use when aging Path MTU values.


Usage:  ffx net dhcpd get option path-mtu-aging-timeout [--timeout <timeout>]
Options  
--help display usage information
--timeout the timeout, in seconds, to be used when again Path MTU values by the mechanism in RFC 1191.
path-mtu-plateau-table

Table of MTU sizes for Path MTU Discovery.


Usage:  ffx net dhcpd get option path-mtu-plateau-table [--mtu-sizes <mtu-sizes...>]
Options  
--help display usage information
--mtu-sizes A list of MTU sizes, ordered from smallest to largest. The smallest value cannot be smaller than 68.
perform-mask-discovery

Flag indicating whether the client should perform subnet mask discovery via ICMP.


Usage:  ffx net dhcpd get option perform-mask-discovery [--do-discovery]
Options  
--help display usage information
--do-discovery a flag indicating whether the client should perform subnet mask discovery via ICMP.
perform-router-discovery

Flag indicating whether the client should solicit routers using Router Discovery.


Usage:  ffx net dhcpd get option perform-router-discovery [--do-discovery]
Options  
--help display usage information
--do-discovery A flag indicating whether the client should solicit routers using Router Discovery as defined in RFC 1256.
policy-filter

Policy filters for non-local source routing.


Usage:  ffx net dhcpd get option policy-filter [--addresses <addresses...>]
Options  
--help display usage information
--addresses a list of IP Address and Subnet Mask pairs. If an incoming source-routed packet has a next-hop that does not match one of these pairs, then the packet will be dropped.
pop3-server

POP3 servers available to the client.


Usage:  ffx net dhcpd get option pop3-server [--pop3-servers <pop3-servers...>]
Options  
--help display usage information
--pop3-servers a list of Post Office Protocol (POP3) server addresses available to the client, listed in order of preference.
rebinding-time-value

Time interval from address assignment at which the client transitions to a Rebinding state.


Usage:  ffx net dhcpd get option rebinding-time-value [--interval <interval>]
Options  
--help display usage information
--interval the time interval, in seconds, after address assignment at which the client will transition to the Rebinding state.
renewal-time-value

Time interval from address assignment at which the client transitions to a Renewing state.


Usage:  ffx net dhcpd get option renewal-time-value [--interval <interval>]
Options  
--help display usage information
--interval the time interval, in seconds, after address assignment at which the client will transition to the Renewing state.
resource-location-server

RFC 887 Resource Location servers available to the client.


Usage:  ffx net dhcpd get option resource-location-server [--resource-location-servers <resource-location-servers...>]
Options  
--help display usage information
--resource-location-servers a list of RFC 887 Resource Location servers available to the client, in order of preference.
root-path

Path name to a TFTP-retrievable file containing vendor-extension information.


Usage:  ffx net dhcpd get option root-path [--path <path>]
Options  
--help display usage information
--path the path name to a TFTP-retrievable file. This file contains data which can be interpreted as the BOOTP vendor-extension field. Unlike the BOOTP vendor-extension field, this file has an unconstrained length and any references to Tag 18 are ignored.
router

The routers within a client's subnet.


Usage:  ffx net dhcpd get option router [--routers <routers...>]
Options  
--help display usage information
--routers a list of the routers in a client's subnet, listed in order of preference.
router-solicitation-address

Destination address for Router Solicitation requests.


Usage:  ffx net dhcpd get option router-solicitation-address [--addr <addr>]
Options  
--help display usage information
--addr the address to which the client should transmit Router Solicitation requests.
smtp-server

SMTP servers available to the client.


Usage:  ffx net dhcpd get option smtp-server [--smtp-servers <smtp-servers...>]
Options  
--help display usage information
--smtp-servers a list of Simple Mail Transport Protocol (SMTP) server address available to the client, listed in order of preference.
static-route

Static Routes which the client should put in its routing cache.


Usage:  ffx net dhcpd get option static-route [--routes <routes...>]
Options  
--help display usage information
--routes a list of Destination address/Next-hop address pairs defining static routes for the client's routing table. The routes should be listed in descending order of priority. It is illegal to use 0.0.0.0 as the destination in a static route.
stda-server

StreetTalk Directory Assistance servers available to the client.


Usage:  ffx net dhcpd get option stda-server [--stda-servers <stda-servers...>]
Options  
--help display usage information
--stda-servers a list of StreetTalk Directory Assistance server addresses available to the client, listed in order of preference.
street-talk-server

StreetTalk servers available to the client.


Usage:  ffx net dhcpd get option street-talk-server [--streettalk-servers <streettalk-servers...>]
Options  
--help display usage information
--streettalk-servers a list of StreetTalk server addresses available to the client, listed in order of preference.
subnet-mask

The client's subnet mask.


Usage:  ffx net dhcpd get option subnet-mask [--mask <mask>]
Options  
--help display usage information
--mask a 32-bit IPv4 subnet mask.
swap-server

Address of the client's swap server.


Usage:  ffx net dhcpd get option swap-server [--address <address>]
Options  
--help display usage information
--address the address of the client's swap server.
tcp-default-ttl

Default time-to-live for outgoing TCP segments.


Usage:  ffx net dhcpd get option tcp-default-ttl [--ttl <ttl>]
Options  
--help display usage information
--ttl the default time-to-live that the client should use for outgoing TCP segments. The minimum value is 1.
tcp-keepalive-garbage

Flag specifying whether the client should send TCP keepalive messages with an octet of garbage.


Usage:  ffx net dhcpd get option tcp-keepalive-garbage [--send-garbage]
Options  
--help display usage information
--send-garbage a flag specifying whether the client should send TCP keepalive messages with an octet of garbage for compatibility with older implementations.
tcp-keepalive-interval

Interval the client should wait before sending a TCP keepalive message.


Usage:  ffx net dhcpd get option tcp-keepalive-interval [--interval <interval>]
Options  
--help display usage information
--interval the interval, in seconds, the client should wait before sending a TCP keepalive message. A value of 0 indicates that the client should not send keepalive messages unless specifically requested by an application.
tftp-server-name

TFTP server available to the client.


Usage:  ffx net dhcpd get option tftp-server-name [--name <name>]
Options  
--help display usage information
--name the TFTP server name available to the client. This option should be used when the sname field has been overloaded to carry options.
time-offset

The client's offset from UTC.


Usage:  ffx net dhcpd get option time-offset [--offset <offset>]
Options  
--help display usage information
--offset the client's offset from UTC in seconds. A positive offset is east of the zero meridian, and a negative offset is west of the zero meridian.
time-server

Time Protocol servers available to the client.


Usage:  ffx net dhcpd get option time-server [--time-servers <time-servers...>]
Options  
--help display usage information
--time-servers a list of time servers available to the client, in order of preference.
trailer-encapsulation

Flag specifying whether the client should negotiate the use of trailers in ARP.


Usage:  ffx net dhcpd get option trailer-encapsulation [--trailers]
Options  
--help display usage information
--trailers a flag specifying whether the client negotiate the use of trailers when using ARP, per RFC 893.
vendor-specific-information

Option for exchanging vendor-specific information between the DHCP client and DHCP server.


Usage:  ffx net dhcpd get option vendor-specific-information [--data <data...>]
Options  
--help display usage information
--data an opaque object of octets for exchanging vendor-specific information.
x-window-system-display-manager

X window System Display Manager systems available to the client.


Usage:  ffx net dhcpd get option x-window-system-display-manager [--display-servers <display-servers...>]
Options  
--help display usage information
--display-servers a list of X Window System Display Manager system addresses available to the client, listed in order of preference.
x-window-system-font-server

X Window System Font servers available to the client.


Usage:  ffx net dhcpd get option x-window-system-font-server [--servers <servers...>]
Options  
--help display usage information
--servers a list of X Window System Font server addresses available to the client, listed in order of preference.
parameter

A secondary command indicating a server parameter argument.


Usage:  ffx net dhcpd get parameter [subcommand...]
Options  
--help display usage information
Subcommands  
address-pool The pool of addresses which the DHCP server manages.
arp-probe Enables server behavior where the server ARPs an IP address prior to issuing it in a lease.
bound-device-names The names of the network devices on which the server will listen.
ip-addrs The IPv4 addresses to which the server is bound.
lease-length The duration of leases offered by the server.
permitted-macs The client MAC addresses which the server will issue leases to.
statically-assigned-addrs Addresses in the AddressPool which will only be leased to specified clients. Assigned addresses will be paired with hosts in order, e.g. hosts (A, B, C) and addresses (1, 2, 3) pair as ((A, 1), (B, 2), (C, 3)).
address-pool

The pool of addresses which the DHCP server manages.


Usage:  ffx net dhcpd get parameter address-pool [--prefix-length <prefix-length>] [--range-start <range-start>] [--range-stop <range-stop>]
Options  
--help display usage information
--prefix-length the prefix length of the network's subnet mask
--range-start the starting address, inclusive, of the range of addresses which the DHCP server will lease to clients
--range-stop the ending address, inclusive, of the range of addresses which the server will to clients
arp-probe

Enables server behavior where the server ARPs an IP address prior to issuing it in a lease.


Usage:  ffx net dhcpd get parameter arp-probe [--enabled]
Options  
--help display usage information
--enabled enables server behavior where the server ARPs an IP address prior to issuing it in a lease. If the server receives a response, the server will mark the address as in-use and try again with a different address. By default, this behavior is disabled.
bound-device-names

The names of the network devices on which the server will listen.


Usage:  ffx net dhcpd get parameter bound-device-names [names...]
Options  
--help display usage information
ip-addrs

The IPv4 addresses to which the server is bound.


Usage:  ffx net dhcpd get parameter ip-addrs [--addrs <addrs...>]
Options  
--help display usage information
--addrs A list of IPv4 Addresses to which the server is bound.
lease-length

The duration of leases offered by the server.


Usage:  ffx net dhcpd get parameter lease-length [--default <default>] [--max <max>]
Options  
--help display usage information
--default the default lease length, in seconds, to be issued to clients.
--max the maximum lease length value, in seconds, which the server will issue to clients who have requested a specific lease length. With the default value of 0, the max lease length is equivalent to the default lease length.
permitted-macs

The client MAC addresses which the server will issue leases to.


Usage:  ffx net dhcpd get parameter permitted-macs [--macs <macs...>]
Options  
--help display usage information
--macs the client MAC addresses which the server will issue leases to. By default, the server will not have a permitted MAC list, in which case it will attempt to issue a lease to every client which requests one. If permitted_macs has a non-zero length then the server will only respond to lease requests from clients with a MAC in the list.
statically-assigned-addrs

Addresses in the AddressPool which will only be leased to specified clients. Assigned addresses will be paired with hosts in order, e.g. hosts (A, B, C) and addresses (1, 2, 3) pair as ((A, 1), (B, 2), (C, 3)).


Usage:  ffx net dhcpd get parameter statically-assigned-addrs [--hosts <hosts...>] [--assigned-addrs <assigned-addrs...>]
Options  
--help display usage information
--hosts hosts which will be leased the addresses reserved by assigned_addrs.
--assigned-addrs addresses in the AddressPool which will not be leased to clients. Typically, a network administrator will statically assign these addresses to always-on network devices which should always have the same IP address, such as network printers.

list

A primary command to list the values of all DHCP options or server parameters.


Usage:  ffx net dhcpd list [subcommand...]
Options  
--help display usage information
Subcommands  
option Perform the command on DHCP options.
parameter Perform the command on server parameters.
option

Perform the command on DHCP options.


Usage:  ffx net dhcpd list option
Options  
--help display usage information
parameter

Perform the command on server parameters.


Usage:  ffx net dhcpd list parameter
Options  
--help display usage information

reset

A primary command to reset the values of all DHCP options or server parameters.


Usage:  ffx net dhcpd reset [subcommand...]
Options  
--help display usage information
Subcommands  
option Perform the command on DHCP options.
parameter Perform the command on server parameters.
option

Perform the command on DHCP options.


Usage:  ffx net dhcpd reset option
Options  
--help display usage information
parameter

Perform the command on server parameters.


Usage:  ffx net dhcpd reset parameter
Options  
--help display usage information

set

A primary command to set the value of a DHCP option or server parameter.


Usage:  ffx net dhcpd set [subcommand...]
Options  
--help display usage information
Subcommands  
option A secondary command indicating a DHCP option argument.
parameter A secondary command indicating a server parameter argument.
option

A secondary command indicating a DHCP option argument.


Usage:  ffx net dhcpd set option [subcommand...]
Options  
--help display usage information
Subcommands  
all-subnets-local Flag indicating if all subnets of the connected network have the same MTU.
arp-cache-timeout Timeout for ARP cache entries.
boot-file-size Size of the default boot image for the client.
bootfile-name Bootfile name for the client.
broadcast-address Broadcast address of the client's subnet.
cookie-server RFC 865 Cookie servers available to the client.
default-finger-server Default Finger servers available to the client.
default-ip-ttl Default time-to-live to use on outgoing IP datagrams.
default-irc-server Default IRC servers available to the client.
default-www-server Default WWW servers available to the client.
domain-name Domain name of the client.
domain-name-server Domain Name System servers available to the client.
ethernet-encapsulation Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation.
extensions-path Path name to a TFTP-retrievable file containing vendor-extension information.
host-name Name of the client.
impress-server Imagen Impress servers available to the client.
interface-mtu MTU for the client's interface.
ip-forwarding Flag enabling/disabling IP layer packet forwarding.
log-server MIT-LCS UDP Log servers available to the client.
lpr-server RFC 1179 Line Printer servers available to the client.
mask-supplier Flag indicating whether the client should respond to subnet mask discovery requests via ICMP.
max-datagram-reassembly-size Maximum sized datagram that the client should be able to reassemble.
max-message-size Maximum length of a DHCP message that the participant is willing to accept.
merit-dump-file Path name of a core dump file.
mobile-ip-home-agent Mobile IP home agents available to the client.
name-server IEN 116 Name servers available to the client.
net-bios-over-tcpip-distribution-server NetBIOS datagram distribution servers available to the client.
net-bios-over-tcpip-name-server NetBIOS name servers available to the client.
net-bios-over-tcpip-node-type The NetBIOS node type which should be used by the client.
net-bios-over-tcpip-scope NetBIOS scope parameter for the client.
network-information-servers Network Information Service servers available to the client.
network-information-service-domain Name of the client's Network Information Service domain.
network-information-service-plus-domain Network Information System+ domain name.
network-information-service-plus-servers Network Information System+ servers available to the client.
network-time-protocol-servers Network Time Protocol servers available to the client.
nntp-server NNTP servers available to the client.
non-local-source-routing Flag enabling/disabling forwarding of IP packets with non-local source routes.
path-mtu-aging-timeout Timeout to use when aging Path MTU values.
path-mtu-plateau-table Table of MTU sizes for Path MTU Discovery.
perform-mask-discovery Flag indicating whether the client should perform subnet mask discovery via ICMP.
perform-router-discovery Flag indicating whether the client should solicit routers using Router Discovery.
policy-filter Policy filters for non-local source routing.
pop3-server POP3 servers available to the client.
rebinding-time-value Time interval from address assignment at which the client transitions to a Rebinding state.
renewal-time-value Time interval from address assignment at which the client transitions to a Renewing state.
resource-location-server RFC 887 Resource Location servers available to the client.
root-path Path name to a TFTP-retrievable file containing vendor-extension information.
router The routers within a client's subnet.
router-solicitation-address Destination address for Router Solicitation requests.
smtp-server SMTP servers available to the client.
static-route Static Routes which the client should put in its routing cache.
stda-server StreetTalk Directory Assistance servers available to the client.
street-talk-server StreetTalk servers available to the client.
subnet-mask The client's subnet mask.
swap-server Address of the client's swap server.
tcp-default-ttl Default time-to-live for outgoing TCP segments.
tcp-keepalive-garbage Flag specifying whether the client should send TCP keepalive messages with an octet of garbage.
tcp-keepalive-interval Interval the client should wait before sending a TCP keepalive message.
tftp-server-name TFTP server available to the client.
time-offset The client's offset from UTC.
time-server Time Protocol servers available to the client.
trailer-encapsulation Flag specifying whether the client should negotiate the use of trailers in ARP.
vendor-specific-information Option for exchanging vendor-specific information between the DHCP client and DHCP server.
x-window-system-display-manager X window System Display Manager systems available to the client.
x-window-system-font-server X Window System Font servers available to the client.
all-subnets-local

Flag indicating if all subnets of the connected network have the same MTU.


Usage:  ffx net dhcpd set option all-subnets-local [--local]
Options  
--help display usage information
--local a flag indicating if all subents of the IP network to which the client is connected have the same MTU.
arp-cache-timeout

Timeout for ARP cache entries.


Usage:  ffx net dhcpd set option arp-cache-timeout [--timeout <timeout>]
Options  
--help display usage information
--timeout the timeout for ARP cache entries, in seconds.
boot-file-size

Size of the default boot image for the client.


Usage:  ffx net dhcpd set option boot-file-size [--size <size>]
Options  
--help display usage information
--size the size of the client's default boot image in 512-octet blocks.
bootfile-name

Bootfile name for the client.


Usage:  ffx net dhcpd set option bootfile-name [--name <name>]
Options  
--help display usage information
--name the bootfile name for the client. This option should be used when the file field has been overloaded to carry options.
broadcast-address

Broadcast address of the client's subnet.


Usage:  ffx net dhcpd set option broadcast-address [--addr <addr>]
Options  
--help display usage information
--addr the broadcast address of the client's subnet. Legal values are defined in RFC 1122.

RFC 865 Cookie servers available to the client.


Usage:  ffx net dhcpd set option cookie-server [--cookie-servers <cookie-servers...>]
Options  
--help display usage information
--cookie-servers a list of RFC 865 Cookie servers available to the client, in order of preference.
default-finger-server

Default Finger servers available to the client.


Usage:  ffx net dhcpd set option default-finger-server [--finger-servers <finger-servers...>]
Options  
--help display usage information
--finger-servers a list of default Finger server addresses available to the client, listed in order of preference.
default-ip-ttl

Default time-to-live to use on outgoing IP datagrams.


Usage:  ffx net dhcpd set option default-ip-ttl [--ttl <ttl>]
Options  
--help display usage information
--ttl the default time-to-live to use on outgoing IP datagrams. The value must be between 1 and 255.
default-irc-server

Default IRC servers available to the client.


Usage:  ffx net dhcpd set option default-irc-server [--irc-servers <irc-servers...>]
Options  
--help display usage information
--irc-servers a list of Internet Relay Chat server addresses available to the client, listed in order of preference.
default-www-server

Default WWW servers available to the client.


Usage:  ffx net dhcpd set option default-www-server [--www-servers <www-servers...>]
Options  
--help display usage information
--www-servers a list of default World Wide Web (WWW) server addresses available to the client, listed in order of preference.
domain-name

Domain name of the client.


Usage:  ffx net dhcpd set option domain-name [--name <name>]
Options  
--help display usage information
--name the client's domain name for use in resolving hostnames in the DNS.
domain-name-server

Domain Name System servers available to the client.


Usage:  ffx net dhcpd set option domain-name-server [--domain-name-servers <domain-name-servers...>]
Options  
--help display usage information
--domain-name-servers a list of DNS servers available to the client, in order of preference;
ethernet-encapsulation

Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation.


Usage:  ffx net dhcpd set option ethernet-encapsulation [--encapsulate]
Options  
--help display usage information
--encapsulate a flag specifying that the client should use Ethernet v2 encapsulation when false, and IEEE 802.3 encapsulation when true.
extensions-path

Path name to a TFTP-retrievable file containing vendor-extension information.


Usage:  ffx net dhcpd set option extensions-path [--path <path>]
Options  
--help display usage information
--path the path name to a TFTP-retrievable file. This file contains data which can be interpreted as the BOOTP vendor-extension field. Unlike the BOOTP vendor-extension field, this file has an unconstrained length and any references to Tag 18 are ignored.
host-name

Name of the client.


Usage:  ffx net dhcpd set option host-name [--name <name>]
Options  
--help display usage information
--name the name of client, which may or may not be qualified with the local domain name.
impress-server

Imagen Impress servers available to the client.


Usage:  ffx net dhcpd set option impress-server [--impress-servers <impress-servers...>]
Options  
--help display usage information
--impress-servers a list of Imagen Impress servers available to the client, in order of preference.
interface-mtu

MTU for the client's interface.


Usage:  ffx net dhcpd set option interface-mtu [--mtu <mtu>]
Options  
--help display usage information
--mtu the MTU for the client's interface. Minimum value of 68.
ip-forwarding

Flag enabling/disabling IP layer packet forwarding.


Usage:  ffx net dhcpd set option ip-forwarding [--enabled]
Options  
--help display usage information
--enabled a flag which will enabled IP layer packet forwarding when true.
log-server

MIT-LCS UDP Log servers available to the client.


Usage:  ffx net dhcpd set option log-server [--log-servers <log-servers...>]
Options  
--help display usage information
--log-servers a list of MIT-LCS UDP Log servers available to the client, in order of preference.
lpr-server

RFC 1179 Line Printer servers available to the client.


Usage:  ffx net dhcpd set option lpr-server [--lpr-servers <lpr-servers...>]
Options  
--help display usage information
--lpr-servers a list of RFC 1179 Line Printer servers available to the client, in order of preference.
mask-supplier

Flag indicating whether the client should respond to subnet mask discovery requests via ICMP.


Usage:  ffx net dhcpd set option mask-supplier [--supplier]
Options  
--help display usage information
--supplier a flag indicating whether the client should respond to subnet mask discovery requests via ICMP.
max-datagram-reassembly-size

Maximum sized datagram that the client should be able to reassemble.


Usage:  ffx net dhcpd set option max-datagram-reassembly-size [--size <size>]
Options  
--help display usage information
--size the maximum sized datagram that the client should be able to reassemble, in octets. The minimum legal value is 576.
max-message-size

Maximum length of a DHCP message that the participant is willing to accept.


Usage:  ffx net dhcpd set option max-message-size [--length <length>]
Options  
--help display usage information
--length the maximum length in octets of a DHCP message that the participant is willing to accept. The minimum value is 576.
merit-dump-file

Path name of a core dump file.


Usage:  ffx net dhcpd set option merit-dump-file [--path <path>]
Options  
--help display usage information
--path the path name to the client's core dump in the event the client crashes.
mobile-ip-home-agent

Mobile IP home agents available to the client.


Usage:  ffx net dhcpd set option mobile-ip-home-agent [--home-agents <home-agents...>]
Options  
--help display usage information
--home-agents a list of mobile IP home agent addresses available to the client, listed in order of preference.
name-server

IEN 116 Name servers available to the client.


Usage:  ffx net dhcpd set option name-server [--name-servers <name-servers...>]
Options  
--help display usage information
--name-servers a list of IEN 116 Name servers available to the client, in order of preference.
net-bios-over-tcpip-distribution-server

NetBIOS datagram distribution servers available to the client.


Usage:  ffx net dhcpd set option net-bios-over-tcpip-distribution-server [--servers <servers...>]
Options  
--help display usage information
--servers a list of NetBIOS datagram distribution servers available to the client, listed in order of preference.
net-bios-over-tcpip-name-server

NetBIOS name servers available to the client.


Usage:  ffx net dhcpd set option net-bios-over-tcpip-name-server [--servers <servers...>]
Options  
--help display usage information
--servers a list of NetBIOS name server addresses available to the client, listed in order of preference.
net-bios-over-tcpip-node-type

The NetBIOS node type which should be used by the client.


Usage:  ffx net dhcpd set option net-bios-over-tcpip-node-type [subcommand...]
Options  
--help display usage information
Subcommands  
b-node A B node type.
h-node A H node type.
m-node A M node type.
p-node A P node type.
# b-node

A B node type.


Usage:  ffx net dhcpd set option net-bios-over-tcpip-node-type b-node
Options  
--help display usage information
# h-node

A H node type.


Usage:  ffx net dhcpd set option net-bios-over-tcpip-node-type h-node
Options  
--help display usage information
# m-node

A M node type.


Usage:  ffx net dhcpd set option net-bios-over-tcpip-node-type m-node
Options  
--help display usage information
# p-node

A P node type.


Usage:  ffx net dhcpd set option net-bios-over-tcpip-node-type p-node
Options  
--help display usage information
net-bios-over-tcpip-scope

NetBIOS scope parameter for the client.


Usage:  ffx net dhcpd set option net-bios-over-tcpip-scope [--scope <scope>]
Options  
--help display usage information
--scope the NetBIOS over TCP/IP scope parameter, as defined in RFC 1001, for the client.
network-information-servers

Network Information Service servers available to the client.


Usage:  ffx net dhcpd set option network-information-servers [--servers <servers...>]
Options  
--help display usage information
--servers a list of Network Information Service server addresses available to the client, listed in order of preference.
network-information-service-domain

Name of the client's Network Information Service domain.


Usage:  ffx net dhcpd set option network-information-service-domain [--domain-name <domain-name>]
Options  
--help display usage information
--domain-name the name of the client's Network Information Service domain.
network-information-service-plus-domain

Network Information System+ domain name.


Usage:  ffx net dhcpd set option network-information-service-plus-domain [--domain-name <domain-name>]
Options  
--help display usage information
--domain-name the name of the client's Network Information System+ domain.
network-information-service-plus-servers

Network Information System+ servers available to the client.


Usage:  ffx net dhcpd set option network-information-service-plus-servers [--servers <servers...>]
Options  
--help display usage information
--servers a list of Network Information System+ server addresses available to the client, listed in order of preference.
network-time-protocol-servers

Network Time Protocol servers available to the client.


Usage:  ffx net dhcpd set option network-time-protocol-servers [--servers <servers...>]
Options  
--help display usage information
--servers a list of Network Time Protocol (NTP) server addresses available to the client, listed in order of preference.
nntp-server

NNTP servers available to the client.


Usage:  ffx net dhcpd set option nntp-server [--nntp-servers <nntp-servers...>]
Options  
--help display usage information
--nntp-servers a list Network News Transport Protocol (NNTP) server addresses available to the client, listed in order of preference.
non-local-source-routing

Flag enabling/disabling forwarding of IP packets with non-local source routes.


Usage:  ffx net dhcpd set option non-local-source-routing [--enabled]
Options  
--help display usage information
--enabled a flag which will enable forwarding of IP packets with non-local source routes.
path-mtu-aging-timeout

Timeout to use when aging Path MTU values.


Usage:  ffx net dhcpd set option path-mtu-aging-timeout [--timeout <timeout>]
Options  
--help display usage information
--timeout the timeout, in seconds, to be used when again Path MTU values by the mechanism in RFC 1191.
path-mtu-plateau-table

Table of MTU sizes for Path MTU Discovery.


Usage:  ffx net dhcpd set option path-mtu-plateau-table [--mtu-sizes <mtu-sizes...>]
Options  
--help display usage information
--mtu-sizes A list of MTU sizes, ordered from smallest to largest. The smallest value cannot be smaller than 68.
perform-mask-discovery

Flag indicating whether the client should perform subnet mask discovery via ICMP.


Usage:  ffx net dhcpd set option perform-mask-discovery [--do-discovery]
Options  
--help display usage information
--do-discovery a flag indicating whether the client should perform subnet mask discovery via ICMP.
perform-router-discovery

Flag indicating whether the client should solicit routers using Router Discovery.


Usage:  ffx net dhcpd set option perform-router-discovery [--do-discovery]
Options  
--help display usage information
--do-discovery A flag indicating whether the client should solicit routers using Router Discovery as defined in RFC 1256.
policy-filter

Policy filters for non-local source routing.


Usage:  ffx net dhcpd set option policy-filter [--addresses <addresses...>]
Options  
--help display usage information
--addresses a list of IP Address and Subnet Mask pairs. If an incoming source-routed packet has a next-hop that does not match one of these pairs, then the packet will be dropped.
pop3-server

POP3 servers available to the client.


Usage:  ffx net dhcpd set option pop3-server [--pop3-servers <pop3-servers...>]
Options  
--help display usage information
--pop3-servers a list of Post Office Protocol (POP3) server addresses available to the client, listed in order of preference.
rebinding-time-value

Time interval from address assignment at which the client transitions to a Rebinding state.


Usage:  ffx net dhcpd set option rebinding-time-value [--interval <interval>]
Options  
--help display usage information
--interval the time interval, in seconds, after address assignment at which the client will transition to the Rebinding state.
renewal-time-value

Time interval from address assignment at which the client transitions to a Renewing state.


Usage:  ffx net dhcpd set option renewal-time-value [--interval <interval>]
Options  
--help display usage information
--interval the time interval, in seconds, after address assignment at which the client will transition to the Renewing state.
resource-location-server

RFC 887 Resource Location servers available to the client.


Usage:  ffx net dhcpd set option resource-location-server [--resource-location-servers <resource-location-servers...>]
Options  
--help display usage information
--resource-location-servers a list of RFC 887 Resource Location servers available to the client, in order of preference.
root-path

Path name to a TFTP-retrievable file containing vendor-extension information.


Usage:  ffx net dhcpd set option root-path [--path <path>]
Options  
--help display usage information
--path the path name to a TFTP-retrievable file. This file contains data which can be interpreted as the BOOTP vendor-extension field. Unlike the BOOTP vendor-extension field, this file has an unconstrained length and any references to Tag 18 are ignored.
router

The routers within a client's subnet.


Usage:  ffx net dhcpd set option router [--routers <routers...>]
Options  
--help display usage information
--routers a list of the routers in a client's subnet, listed in order of preference.
router-solicitation-address

Destination address for Router Solicitation requests.


Usage:  ffx net dhcpd set option router-solicitation-address [--addr <addr>]
Options  
--help display usage information
--addr the address to which the client should transmit Router Solicitation requests.
smtp-server

SMTP servers available to the client.


Usage:  ffx net dhcpd set option smtp-server [--smtp-servers <smtp-servers...>]
Options  
--help display usage information
--smtp-servers a list of Simple Mail Transport Protocol (SMTP) server address available to the client, listed in order of preference.
static-route

Static Routes which the client should put in its routing cache.


Usage:  ffx net dhcpd set option static-route [--routes <routes...>]
Options  
--help display usage information
--routes a list of Destination address/Next-hop address pairs defining static routes for the client's routing table. The routes should be listed in descending order of priority. It is illegal to use 0.0.0.0 as the destination in a static route.
stda-server

StreetTalk Directory Assistance servers available to the client.


Usage:  ffx net dhcpd set option stda-server [--stda-servers <stda-servers...>]
Options  
--help display usage information
--stda-servers a list of StreetTalk Directory Assistance server addresses available to the client, listed in order of preference.
street-talk-server

StreetTalk servers available to the client.


Usage:  ffx net dhcpd set option street-talk-server [--streettalk-servers <streettalk-servers...>]
Options  
--help display usage information
--streettalk-servers a list of StreetTalk server addresses available to the client, listed in order of preference.
subnet-mask

The client's subnet mask.


Usage:  ffx net dhcpd set option subnet-mask [--mask <mask>]
Options  
--help display usage information
--mask a 32-bit IPv4 subnet mask.
swap-server

Address of the client's swap server.


Usage:  ffx net dhcpd set option swap-server [--address <address>]
Options  
--help display usage information
--address the address of the client's swap server.
tcp-default-ttl

Default time-to-live for outgoing TCP segments.


Usage:  ffx net dhcpd set option tcp-default-ttl [--ttl <ttl>]
Options  
--help display usage information
--ttl the default time-to-live that the client should use for outgoing TCP segments. The minimum value is 1.
tcp-keepalive-garbage

Flag specifying whether the client should send TCP keepalive messages with an octet of garbage.


Usage:  ffx net dhcpd set option tcp-keepalive-garbage [--send-garbage]
Options  
--help display usage information
--send-garbage a flag specifying whether the client should send TCP keepalive messages with an octet of garbage for compatibility with older implementations.
tcp-keepalive-interval

Interval the client should wait before sending a TCP keepalive message.


Usage:  ffx net dhcpd set option tcp-keepalive-interval [--interval <interval>]
Options  
--help display usage information
--interval the interval, in seconds, the client should wait before sending a TCP keepalive message. A value of 0 indicates that the client should not send keepalive messages unless specifically requested by an application.
tftp-server-name

TFTP server available to the client.


Usage:  ffx net dhcpd set option tftp-server-name [--name <name>]
Options  
--help display usage information
--name the TFTP server name available to the client. This option should be used when the sname field has been overloaded to carry options.
time-offset

The client's offset from UTC.


Usage:  ffx net dhcpd set option time-offset [--offset <offset>]
Options  
--help display usage information
--offset the client's offset from UTC in seconds. A positive offset is east of the zero meridian, and a negative offset is west of the zero meridian.
time-server

Time Protocol servers available to the client.


Usage:  ffx net dhcpd set option time-server [--time-servers <time-servers...>]
Options  
--help display usage information
--time-servers a list of time servers available to the client, in order of preference.
trailer-encapsulation

Flag specifying whether the client should negotiate the use of trailers in ARP.


Usage:  ffx net dhcpd set option trailer-encapsulation [--trailers]
Options  
--help display usage information
--trailers a flag specifying whether the client negotiate the use of trailers when using ARP, per RFC 893.
vendor-specific-information

Option for exchanging vendor-specific information between the DHCP client and DHCP server.


Usage:  ffx net dhcpd set option vendor-specific-information [--data <data...>]
Options  
--help display usage information
--data an opaque object of octets for exchanging vendor-specific information.
x-window-system-display-manager

X window System Display Manager systems available to the client.


Usage:  ffx net dhcpd set option x-window-system-display-manager [--display-servers <display-servers...>]
Options  
--help display usage information
--display-servers a list of X Window System Display Manager system addresses available to the client, listed in order of preference.
x-window-system-font-server

X Window System Font servers available to the client.


Usage:  ffx net dhcpd set option x-window-system-font-server [--servers <servers...>]
Options  
--help display usage information
--servers a list of X Window System Font server addresses available to the client, listed in order of preference.
parameter

A secondary command indicating a server parameter argument.


Usage:  ffx net dhcpd set parameter [subcommand...]
Options  
--help display usage information
Subcommands  
address-pool The pool of addresses which the DHCP server manages.
arp-probe Enables server behavior where the server ARPs an IP address prior to issuing it in a lease.
bound-device-names The names of the network devices on which the server will listen.
ip-addrs The IPv4 addresses to which the server is bound.
lease-length The duration of leases offered by the server.
permitted-macs The client MAC addresses which the server will issue leases to.
statically-assigned-addrs Addresses in the AddressPool which will only be leased to specified clients. Assigned addresses will be paired with hosts in order, e.g. hosts (A, B, C) and addresses (1, 2, 3) pair as ((A, 1), (B, 2), (C, 3)).
address-pool

The pool of addresses which the DHCP server manages.


Usage:  ffx net dhcpd set parameter address-pool [--prefix-length <prefix-length>] [--range-start <range-start>] [--range-stop <range-stop>]
Options  
--help display usage information
--prefix-length the prefix length of the network's subnet mask
--range-start the starting address, inclusive, of the range of addresses which the DHCP server will lease to clients
--range-stop the ending address, inclusive, of the range of addresses which the server will to clients
arp-probe

Enables server behavior where the server ARPs an IP address prior to issuing it in a lease.


Usage:  ffx net dhcpd set parameter arp-probe [--enabled]
Options  
--help display usage information
--enabled enables server behavior where the server ARPs an IP address prior to issuing it in a lease. If the server receives a response, the server will mark the address as in-use and try again with a different address. By default, this behavior is disabled.
bound-device-names

The names of the network devices on which the server will listen.


Usage:  ffx net dhcpd set parameter bound-device-names [names...]
Options  
--help display usage information
ip-addrs

The IPv4 addresses to which the server is bound.


Usage:  ffx net dhcpd set parameter ip-addrs [--addrs <addrs...>]
Options  
--help display usage information
--addrs A list of IPv4 Addresses to which the server is bound.
lease-length

The duration of leases offered by the server.


Usage:  ffx net dhcpd set parameter lease-length [--default <default>] [--max <max>]
Options  
--help display usage information
--default the default lease length, in seconds, to be issued to clients.
--max the maximum lease length value, in seconds, which the server will issue to clients who have requested a specific lease length. With the default value of 0, the max lease length is equivalent to the default lease length.
permitted-macs

The client MAC addresses which the server will issue leases to.


Usage:  ffx net dhcpd set parameter permitted-macs [--macs <macs...>]
Options  
--help display usage information
--macs the client MAC addresses which the server will issue leases to. By default, the server will not have a permitted MAC list, in which case it will attempt to issue a lease to every client which requests one. If permitted_macs has a non-zero length then the server will only respond to lease requests from clients with a MAC in the list.
statically-assigned-addrs

Addresses in the AddressPool which will only be leased to specified clients. Assigned addresses will be paired with hosts in order, e.g. hosts (A, B, C) and addresses (1, 2, 3) pair as ((A, 1), (B, 2), (C, 3)).


Usage:  ffx net dhcpd set parameter statically-assigned-addrs [--hosts <hosts...>] [--assigned-addrs <assigned-addrs...>]
Options  
--help display usage information
--hosts hosts which will be leased the addresses reserved by assigned_addrs.
--assigned-addrs addresses in the AddressPool which will not be leased to clients. Typically, a network administrator will statically assign these addresses to always-on network devices which should always have the same IP address, such as network printers.

start

A primary command to start the DHCP server.


Usage:  ffx net dhcpd start
Options  
--help display usage information

stop

A primary command to stop the DHCP server.


Usage:  ffx net dhcpd stop
Options  
--help display usage information

dns

commands to control the dns resolver


Usage:  ffx net dns [subcommand...]
Options  
--help display usage information
Subcommands  
lookup performs dns resolution on the specified hostname

lookup

performs dns resolution on the specified hostname


Usage:  ffx net dns lookup [--ipv4 <ipv4>] [--ipv6 <ipv6>] [--sort <sort>] hostname
Options  
--help display usage information
--ipv4 include ipv4 results (defaults to true)
--ipv6 include ipv6 results (defaults to true)
--sort sort addresses in order of preference (defaults to true)

filter

commands for configuring packet filtering


Usage:  ffx net filter [subcommand...]
Options  
--help display usage information
Subcommands  
create A command to create new filtering resources
list A command to list filtering configuration.
remove A command to remove existing filtering resources

create

A command to create new filtering resources


Usage:  ffx net filter create --controller <controller> [--idempotent] [subcommand...]
Options  
--help display usage information
--controller the name of the controller to create (or connect to, if existing)
--idempotent whether the resource creation should be idempotent, i.e. succeed even if the resource already exists
Subcommands  
namespace A command to specify a filtering namespace
routine A command to specify a filtering routine
rule A command to specify a filtering rule
namespace

A command to specify a filtering namespace


Usage:  ffx net filter create namespace --name <name> [--domain <domain>]
Options  
--help display usage information
--name the name of the namespace
--domain the IP domain of the namespace
routine

A command to specify a filtering routine


Usage:  ffx net filter create routine --namespace <namespace> --name <name> --type <type> [--hook <hook>] [--priority <priority>]
Options  
--help display usage information
--namespace the namespace that contains the routine
--name the name of the routine
--type the type of the routine (IP or NAT)
--hook the hook on which the routine is installed (optional)
--priority the priority of the routine on its hook (optional)
rule

A command to specify a filtering rule


Usage:  ffx net filter create rule --namespace <namespace> --routine <routine> --index <index> [--in-interface <in-interface>] [--out-interface <out-interface>] [--src-addr <src-addr>] [--dst-addr <dst-addr>] [--transport-protocol <transport-protocol>] [--src-port <src-port>] [--dst-port <dst-port>] [subcommand...]
Options  
--help display usage information
--namespace the namespace that contains the rule
--routine the routine that contains the rule
--index the index of the rule
--in-interface a matcher for the ingress interface of the packet (optional) Accepted formats are any of "id:"
--out-interface a matcher for the egress interface of the packet (optional) Accepted formats are any of "id:"
--src-addr a matcher for the source address of the packet (optional) Accepted formats are any of "subnet:"
--dst-addr a matcher for the destination address of the packet (optional) Accepted formats are any of "subnet:"
--transport-protocol a matcher for the transport protocol of the packet (optional) Accepted protocols are "tcp"
--src-port a matcher for the source port of the packet (optional) Must be accompanied by a transport protocol matcher for either TCP or UDP. Accepted format is "..=". Can be prefixed with a ! for inverse match.
--dst-port a matcher for the destination port of the packet (optional) Must be accompanied by a transport protocol matcher for either TCP or UDP. Accepted format is "..=". Can be prefixed with a ! for inverse match.
Subcommands  
accept The fuchsia.net.filter/Action.Accept action.
drop The fuchsia.net.filter/Action.Drop action.
jump The fuchsia.net.filter/Action.Jump action.
masquerade The fuchsia.net.filter/Action.Masquerade action. The source port range to use to rewrite the packet is optional, but --min-src-port and --max-src-port must either both be specified, or neither.
redirect The fuchsia.net.filter/Action.Redirect action. The destination port range to which to redirect the packet is optional, but --min-dst-port and --max-dst-port must either both be specified, or neither.
return The fuchsia.net.filter/Action.Return action.
tproxy The fuchsia.net.filter/Action.TransparentProxy action. Both --addr and --port are optional, but at least one must be specified.
accept

The fuchsia.net.filter/Action.Accept action.


Usage:  ffx net filter create rule accept
Options  
--help display usage information
drop

The fuchsia.net.filter/Action.Drop action.


Usage:  ffx net filter create rule drop
Options  
--help display usage information
jump

The fuchsia.net.filter/Action.Jump action.


Usage:  ffx net filter create rule jump target
Options  
--help display usage information
masquerade

The fuchsia.net.filter/Action.Masquerade action. The source port range to use to rewrite the packet is optional, but --min-src-port and --max-src-port must either both be specified, or neither.


Usage:  ffx net filter create rule masquerade [--src-port <src-port>]
Options  
--help display usage information
--src-port the source port range used to rewrite the packet (optional)
redirect

The fuchsia.net.filter/Action.Redirect action. The destination port range to which to redirect the packet is optional, but --min-dst-port and --max-dst-port must either both be specified, or neither.


Usage:  ffx net filter create rule redirect [--dst-port <dst-port>]
Options  
--help display usage information
--dst-port the destination port range used to rewrite the packet (optional)
return

The fuchsia.net.filter/Action.Return action.


Usage:  ffx net filter create rule return
Options  
--help display usage information
tproxy

The fuchsia.net.filter/Action.TransparentProxy action. Both --addr and --port are optional, but at least one must be specified.


Usage:  ffx net filter create rule tproxy [--addr <addr>] [--port <port>]
Options  
--help display usage information
--addr the bound address of the local socket to redirect the packet to (optional)
--port the bound port of the local socket to redirect the packet to (optional, must be nonzero)

list

A command to list filtering configuration.


Usage:  ffx net filter list
Options  
--help display usage information

remove

A command to remove existing filtering resources


Usage:  ffx net filter remove --controller <controller> [--idempotent] [subcommand...]
Options  
--help display usage information
--controller the name of the controller that owns the resource
--idempotent whether the resource removal should be idempotent, i.e. succeed even if the resource does not exist
Subcommands  
namespace A command to identify a filtering namespace
routine A command to identify a filtering routine
rule A command to identify a filtering rule
namespace

A command to identify a filtering namespace


Usage:  ffx net filter remove namespace --name <name>
Options  
--help display usage information
--name the name of the namespace
routine

A command to identify a filtering routine


Usage:  ffx net filter remove routine --namespace <namespace> --name <name>
Options  
--help display usage information
--namespace the namespace that contains the routine
--name the name of the routine
rule

A command to identify a filtering rule


Usage:  ffx net filter remove rule --namespace <namespace> --routine <routine> --index <index>
Options  
--help display usage information
--namespace the namespace that contains the rule
--routine the routine that contains the rule
--index the index of the rule

filter-deprecated

commands for configuring packet filtering with the deprecated API


Usage:  ffx net filter-deprecated [subcommand...]
Options  
--help display usage information
Subcommands  
get-nat-rules gets nat rules
get-rdr-rules gets rdr rules
get-rules gets filter rules
set-nat-rules sets nat rules (see the netfilter::parser library for the NAT rules format)
set-rdr-rules sets rdr rules (see the netfilter::parser library for the RDR rules format)
set-rules sets filter rules (see the netfilter::parser library for the rules format)

get-nat-rules

gets nat rules


Usage:  ffx net filter-deprecated get-nat-rules
Options  
--help display usage information

get-rdr-rules

gets rdr rules


Usage:  ffx net filter-deprecated get-rdr-rules
Options  
--help display usage information

get-rules

gets filter rules


Usage:  ffx net filter-deprecated get-rules
Options  
--help display usage information

set-nat-rules

sets nat rules (see the netfilter::parser library for the NAT rules format)


Usage:  ffx net filter-deprecated set-nat-rules rules
Options  
--help display usage information

set-rdr-rules

sets rdr rules (see the netfilter::parser library for the RDR rules format)


Usage:  ffx net filter-deprecated set-rdr-rules rules
Options  
--help display usage information

set-rules

sets filter rules (see the netfilter::parser library for the rules format)


Usage:  ffx net filter-deprecated set-rules rules
Options  
--help display usage information

if

commands for network interfaces


Usage:  ffx net if [subcommand...]
Options  
--help display usage information
Subcommands  
addr commands for updating network interface addresses
bridge creates a bridge between network interfaces
config get or set interface configuration
disable disables a network interface
enable enables a network interface
get queries a network interface
igmp get or set IGMP configuration
ip-forward get or set IP forwarding for an interface
list lists network interfaces (supports ffx machine output)
mld get or set MLD configuration

addr

commands for updating network interface addresses


Usage:  ffx net if addr [subcommand...]
Options  
--help display usage information
Subcommands  
add adds an address to the network interface
del deletes an address from the network interface
wait waits for an address to be assigned on the network interface. by default waits for any address; if --ipv6 is specified, waits for an IPv6 address.
add

adds an address to the network interface


Usage:  ffx net if addr add [--no-subnet-route] nicid or name:ifname addr prefix
Options  
--help display usage information
--no-subnet-route skip adding a local subnet route for this interface and address
del

deletes an address from the network interface


Usage:  ffx net if addr del nicid or name:ifname addr [prefix]
Options  
--help display usage information
wait

waits for an address to be assigned on the network interface. by default waits for any address; if --ipv6 is specified, waits for an IPv6 address.


Usage:  ffx net if addr wait [--ipv6] nicid or name:ifname
Options  
--help display usage information
--ipv6 wait for an IPv6 address

bridge

creates a bridge between network interfaces


Usage:  ffx net if bridge [nicid or name:ifname...]
Options  
--help display usage information

config

get or set interface configuration


Usage:  ffx net if config [subcommand...]
Options  
--help display usage information
Subcommands  
get get interface configuration
set set interface configuration
get

get interface configuration


Usage:  ffx net if config get
Options  
--help display usage information
set

set interface configuration

Configuration parameters and the values to be set to should be passed in pairs. The names of the configuration parameters are taken from the structure of fuchsia.net.interfaces.admin/Configuration.

The list of supported parameters are: ipv6.ndp.slaac.temporary_address_enabled bool Whether temporary addresses should be generated.


Usage:  ffx net if config set [options...]
Options  
--help display usage information

disable

disables a network interface


Usage:  ffx net if disable nicid or name:ifname
Options  
--help display usage information

enable

enables a network interface


Usage:  ffx net if enable nicid or name:ifname
Options  
--help display usage information

get

queries a network interface


Usage:  ffx net if get nicid or name:ifname
Options  
--help display usage information

igmp

get or set IGMP configuration


Usage:  ffx net if igmp [subcommand...]
Options  
--help display usage information
Subcommands  
get get IGMP configuration for an interface
set set IGMP configuration for an interface
get

get IGMP configuration for an interface


Usage:  ffx net if igmp get nicid or name:ifname
Options  
--help display usage information
set

set IGMP configuration for an interface


Usage:  ffx net if igmp set [--version <version>] nicid or name:ifname
Options  
--help display usage information
--version the version of IGMP to perform.

ip-forward

get or set IP forwarding for an interface


Usage:  ffx net if ip-forward [subcommand...]
Options  
--help display usage information
Subcommands  
get get IP forwarding for an interface
set set IP forwarding for an interface
get

get IP forwarding for an interface


Usage:  ffx net if ip-forward get nicid or name:ifname ip_version
Options  
--help display usage information
set

set IP forwarding for an interface


Usage:  ffx net if ip-forward set nicid or name:ifname ip_version enable
Options  
--help display usage information

list

lists network interfaces (supports ffx machine output)


Usage:  ffx net if list [name_pattern]
Options  
--help display usage information

mld

get or set MLD configuration


Usage:  ffx net if mld [subcommand...]
Options  
--help display usage information
Subcommands  
get get MLD configuration for an interface
set set MLD configuration for an interface
get

get MLD configuration for an interface


Usage:  ffx net if mld get nicid or name:ifname
Options  
--help display usage information
set

set MLD configuration for an interface


Usage:  ffx net if mld set [--version <version>] nicid or name:ifname
Options  
--help display usage information
--version the version of MLD to perform.

log

commands for logging


Usage:  ffx net log [subcommand...]
Options  
--help display usage information
Subcommands  
set-packets log packets to stdout

set-packets

log packets to stdout


Usage:  ffx net log set-packets enabled
Options  
--help display usage information

migration

controls netstack selection for migration from netstack2 to netstack3


Usage:  ffx net migration [subcommand...]
Options  
--help display usage information
Subcommands  
clear clears netstack version for migration configuration.
get prints the currently configured netstack version for migration.
set sets the netstack version at next boot to

clear

clears netstack version for migration configuration.


Usage:  ffx net migration clear
Options  
--help display usage information

get

prints the currently configured netstack version for migration.


Usage:  ffx net migration get
Options  
--help display usage information

set

sets the netstack version at next boot to |ns2| or |ns3|.


Usage:  ffx net migration set version
Options  
--help display usage information

neigh

commands for neighbor tables


Usage:  ffx net neigh [subcommand...]
Options  
--help display usage information
Subcommands  
add adds an entry to the neighbor table
clear removes all entries associated with a network interface from the neighbor table
config commands for the Neighbor Unreachability Detection configuration
del removes an entry from the neighbor table
list lists neighbor table entries (supports ffx machine output)
watch watches neighbor table entries for state changes (supports ffx machine output)

add

adds an entry to the neighbor table


Usage:  ffx net neigh add nicid or name:ifname ip mac
Options  
--help display usage information

clear

removes all entries associated with a network interface from the neighbor table


Usage:  ffx net neigh clear nicid or name:ifname ip_version
Options  
--help display usage information

config

commands for the Neighbor Unreachability Detection configuration


Usage:  ffx net neigh config [subcommand...]
Options  
--help display usage information
Subcommands  
get returns the current NUD configuration options for the provided interface
update updates the current NUD configuration options for the provided interface
get

returns the current NUD configuration options for the provided interface


Usage:  ffx net neigh config get nicid or name:ifname ip_version
Options  
--help display usage information
update

updates the current NUD configuration options for the provided interface


Usage:  ffx net neigh config update [--base-reachable-time <base-reachable-time>] nicid or name:ifname ip_version
Options  
--help display usage information
--base-reachable-time a base duration, in nanoseconds, for computing the random reachable time

del

removes an entry from the neighbor table


Usage:  ffx net neigh del nicid or name:ifname ip
Options  
--help display usage information

list

lists neighbor table entries (supports ffx machine output)


Usage:  ffx net neigh list
Options  
--help display usage information

watch

watches neighbor table entries for state changes (supports ffx machine output)


Usage:  ffx net neigh watch
Options  
--help display usage information

route

commands for routing tables


Usage:  ffx net route [subcommand...]
Options  
--help display usage information
Subcommands  
add adds a route to the route table
del deletes a route from the route table
list lists routes (supports ffx machine output)

add

adds a route to the route table


Usage:  ffx net route add --destination <destination> --netmask <netmask or prefix length> [--gateway <gateway>] [--nicid <nicid or name:ifname>] [--metric <metric>]
Options  
--help display usage information
--destination the network id of the destination network
--netmask the netmask or prefix length corresponding to destination
--gateway the ip address of the first hop router
--nicid the outgoing network interface of the route
--metric the metric for the route

del

deletes a route from the route table


Usage:  ffx net route del --destination <destination> --netmask <netmask or prefix length> [--gateway <gateway>] [--nicid <nicid or name:ifname>] [--metric <metric>]
Options  
--help display usage information
--destination the network id of the destination network
--netmask the netmask or prefix length corresponding to destination
--gateway the ip address of the first hop router
--nicid the outgoing network interface of the route
--metric the metric for the route

list

lists routes (supports ffx machine output)


Usage:  ffx net route list
Options  
--help display usage information

rule

commands for policy-based-routing rules


Usage:  ffx net rule [subcommand...]
Options  
--help display usage information
Subcommands  
list lists rules (supports ffx machine output)

list

lists rules (supports ffx machine output)


Usage:  ffx net rule list
Options  
--help display usage information

package

Create and publish Fuchsia packages


Usage:  ffx package [subcommand...]
Options  
--help display usage information
Subcommands  
archive Archive Fuchsia packages
blob Work with Fuchsia blob files.
build Builds a package.
far Work with Fuchsia Archive Format (FAR) files
file-hash Compute the merkle tree root hash of one or more files.

archive

Archive Fuchsia packages


Usage:  ffx package archive [subcommand...]
Options  
--help display usage information
Subcommands  
add add a file () to an existing package archive (), placing the resulting archive in
cat write the contents of inside the Fuchsia package archive file to stdout
create create a package archive from a package_manifest.json
edit edit the metadata of an existing package archive (), placing the resulting archive in
extract extract the contents of inside the Fuchsia package archive file to the output directory
list List the contents of Fuchia package archive file
remove remove a file () from an existing package archive (), placing the resulting archive in

add

add a file () to an existing package archive (), placing the resulting archive in 


Usage:  ffx package archive add -a <archive> -f <file-to-add> -p <path-of-file-in-archive> -o <output> [-w <overwrite>]
Options  
--help display usage information
-a, --archive package archive
-f, --file-to-add file to add to the package archive
-p, --path-of-file-in-archive the destination path in the archive for
-o, --output the name of the resulting archive. Can be the same as to overwrite
-w, --overwrite if false, refuses to overwrite files in named by

cat

write the contents of inside the Fuchsia package archive file to stdout


Usage:  ffx package archive cat archive far_path
Options  
--help display usage information

create

create a package archive from a package_manifest.json


Usage:  ffx package archive create -o <out> [-r <root-dir>] [--depfile <depfile>] package_manifest
Options  
--help display usage information
-o, --out output package archive
-r, --root-dir root directory for paths in package_manifest.json
--depfile produce a depfile file at the provided path

edit

edit the metadata of an existing package archive (), placing the resulting archive in 


Usage:  ffx package archive edit -a <archive> [--package-name <package-name>] -o <output>
Options  
--help display usage information
-a, --archive package archive
--package-name if specified, change the name of the package (i.e., what appears in meta/package) to .
-o, --output the name of the resulting archive. Can be the same as to overwrite

extract

extract the contents of inside the Fuchsia package archive file to the output directory


Usage:  ffx package archive extract [-o <out>] [--repository <repository>] [--blobs-json] [--namespace] archive
Options  
--help display usage information
-o, --out output directory for writing the extracted files. Defaults to the current directory.
--repository repository of the package
--blobs-json produce a blobs.json file
--namespace extract the package namespace into /pkg

list

List the contents of Fuchia package archive file


Usage:  ffx package archive list [-l] archive
Options  
--help display usage information
-l, --long-format show long information for each entry

remove

remove a file () from an existing package archive (), placing the resulting archive in 


Usage:  ffx package archive remove -a <archive> -f <file-to-remove> -o <output>
Options  
--help display usage information
-a, --archive package archive
-f, --file-to-remove file to add to the package archive
-o, --output the name of the resulting archive. Can be the same as to overwrite

blob

Work with Fuchsia blob files.


Usage:  ffx package blob [subcommand...]
Options  
--help display usage information
Subcommands  
compress Compress one or more blobs
decompress Decompress one or more blobs
hash Compute the merkle tree root hash of one or more delivery blobs or uncompressed blobs.

compress

Compress one or more blobs


Usage:  ffx package blob compress [-t <type>] -o <output> [--hash-as-name] [paths...]
Options  
--help display usage information
-t, --type delivery blob type
-o, --output output compressed blobs into this directory
--hash-as-name use the merkle root of each file as its output name

decompress

Decompress one or more blobs


Usage:  ffx package blob decompress -o <output> [paths...]
Options  
--help display usage information
-o, --output output decompressed blobs into this directory

hash

Compute the merkle tree root hash of one or more delivery blobs or uncompressed blobs.


Usage:  ffx package blob hash [-u] [paths...]
Options  
--help display usage information
-u, --uncompressed blobs are uncompressed instead of delivery blobs

build

Builds a package.


Usage:  ffx package build [-o <out>] --api-level <api-level> [--published-name <published-name>] [--repository <repository>] [--depfile] [--blobs-json] [--blobs-manifest] [--subpackages-build-manifest-path <subpackages-build-manifest-path>] package_build_manifest_path
Options  
--help display usage information
-o, --out directory to save package artifacts
--api-level package API level
--published-name name of the package
--repository repository of the package
--depfile produce a depfile file
--blobs-json produce a blobs.json file
--blobs-manifest produce a blobs.manifest file
--subpackages-build-manifest-path path to the subpackages build manifest file

far

Work with Fuchsia Archive Format (FAR) files


Usage:  ffx package far [subcommand...]
Options  
--help display usage information
Subcommands  
cat Dump the contents of the entry associated with to stdout
create Create a FAR file from a directory. WARNING: this will overwrite if it exists.
extract Extract from to . WARNING: this may overwrite existing files.
list List the entry paths contained in a FAR file

cat

Dump the contents of the entry associated with to stdout


Usage:  ffx package far cat far_file path
Options  
--help display usage information

create

Create a FAR file from a directory. WARNING: this will overwrite if it exists.


Usage:  ffx package far create input_directory output_file
Options  
--help display usage information

extract

Extract from to . WARNING: this may overwrite existing files.


Usage:  ffx package far extract [-v] [-o <output-dir>] far_file [paths...]
Options  
--help display usage information
-v, --verbose verbose output: print file names that were extracted
-o, --output-dir output directory (defaults to current directory, creates the directory if it doesn't exist)

list

List the entry paths contained in a FAR file


Usage:  ffx package far list [-l] far_file
Options  
--help display usage information
-l, --long-format show detailed information for each entry (does nothing if --machine json is specified, which shows everything)

file-hash

Compute the merkle tree root hash of one or more files.


Usage:  ffx package file-hash [paths...]
Options  
--help display usage information

platform

Manage platform build prerequisites


Usage:  ffx platform [subcommand...]
Options  
--help display usage information
Subcommands  
preflight Evaluate suitability for building and running Fuchsia

preflight

Evaluate suitability for building and running Fuchsia


Usage:  ffx platform preflight [--json]
Options  
--help display usage information
--json outputs json instead of human-readable text.

power

Control system power features


Usage:  ffx power [subcommand...]
Options  
--help display usage information
Subcommands  
debugcmd Send a debug command to the Power Manager
system-activity Manipulate SAG power elements

debugcmd

Send a debug command to the Power Manager


Usage:  ffx power debugcmd --node-name <node-name> --command <command> [--args <args...>]
Options  
--help display usage information
--node-name name of target node
--command debug command to send
--args arguments for the debug command

system-activity

Manipulate SAG power elements


Usage:  ffx power system-activity [subcommand...]
Options  
--help display usage information
Subcommands  
application-activity Controls the topology-test-daemon component to manipulate application_activity power element power levels in system_activity_governor.

application-activity

Controls the topology-test-daemon component to manipulate application_activity power element power levels in system_activity_governor.


Usage:  ffx power system-activity application-activity [subcommand...]
Options  
--help display usage information
Subcommands  
start Start application activity on the target
stop Stop application activity on the target

Examples

To change application_activity power level to 1:

    $ ffx power system-activity application-activity start

    To change application_activity power level to 0:

    $ ffx power system-activity application-activity stop

Notes

  • If the topology-test-daemon component is not available to the target, then this command will not
work properly.
start

Start application activity on the target


Usage:  ffx power system-activity application-activity start
Options  
--help display usage information
stop

Stop application activity on the target


Usage:  ffx power system-activity application-activity stop
Options  
--help display usage information

process

Processes related commands


Usage:  ffx process [subcommand...]
Options  
--help display usage information
Subcommands  
filter outputs information about the processes that correspond to the koids input
generate-fuchsia-map outputs the json required to generate a map of all processes and channels
kill Attempts to kill a process by it's KOID or process name.
list outputs a list containing the name and koid of all processes
stack_trace Attempts to get a strack trace a process by it's KOID or process name.
tree outputs the tree of all tasks in the system

filter

outputs information about the processes that correspond to the koids input


Usage:  ffx process filter [process_koids...]
Options  
--help display usage information

generate-fuchsia-map

outputs the json required to generate a map of all processes and channels


Usage:  ffx process generate-fuchsia-map
Options  
--help display usage information

kill

Attempts to kill a process by it's KOID or process name.


Usage:  ffx process kill task_to_kill
Options  
--help display usage information

list

outputs a list containing the name and koid of all processes


Usage:  ffx process list [--verbose]
Options  
--help display usage information
--verbose outputs all processes and the kernel objects owned by each of them

stack_trace

Attempts to get a strack trace a process by it's KOID or process name.


Usage:  ffx process stack_trace task
Options  
--help display usage information

tree

outputs the tree of all tasks in the system


Usage:  ffx process tree [--threads]
Options  
--help display usage information
--threads include threads

product

Discover and access product bundle metadata and image data.


Usage:  ffx product [subcommand...]
Options  
--help display usage information
Subcommands  
create Create a Product Bundle using the outputs of Product Assembly.
download Download Product Bundle from GCS.
get-artifacts Get the paths of a group of artifacts inside a Product Bundle.
get-image-path Get the path of an image inside a Product Bundle based on type and slot.
get-repository Get the info of repository inside a Product Bundle.
get-version Get the product version of a Product Bundle.
list List all available products for a specific SDK version.
lookup Retrieve image data.
show Display a list of details from within a product bundle.

create

Create a Product Bundle using the outputs of Product Assembly.


Usage:  ffx product create --product-name <product-name> --product-version <product-version> --partitions <partitions> [--system-a <system-a>] [--system-b <system-b>] [--system-r <system-r>] [--tuf-keys <tuf-keys>] [--update-package-version-file <update-package-version-file>] [--update-package-epoch <update-package-epoch>] [--virtual-device <virtual-device...>] [--recommended-device <recommended-device>] --out-dir <out-dir> [--delivery-blob-type <delivery-blob-type>] [--with-deprecated-flash-manifest] [--gerrit-size-report <gerrit-size-report>]
Options  
--help display usage information
--product-name product.board label. e.g. "workstation_eng.x64".
--product-version unique version of this product.board.
--partitions path to a partitions config, which lists the physical partitions of the target.
--system-a path to an assembly manifest, which specifies images to put in slot A.
--system-b path to an assembly manifest, which specifies images to put in slot B.
--system-r path to an assembly manifest, which specifies images to put in slot R.
--tuf-keys path to the directory of TUF keys, which should include root.json, snapshot.json, targets.json, and timestamp.json. If provided, then a TUF repository will be created inside the product bundle and filled with the product blobs.
--update-package-version-file file containing the version of the Product to put in the update package.
--update-package-epoch backstop OTA version. Fuchsia will reject updates with a lower epoch.
--virtual-device path to a Virtual Device Specification file to include in the product bundle. May be repeated to include multiple Virtual Devices.
--recommended-device name of a Virtual Device Specification file to mark as the "recommended" device for emulation.
--out-dir directory to write the product bundle.
--delivery-blob-type the type of delivery blob the product needs.
--with-deprecated-flash-manifest create a deprecated flash manifest for backward compatibility.
--gerrit-size-report an optional image size report to generate that indicates the sizes of the images when mapped to partitions.

download

Download Product Bundle from GCS.


Usage:  ffx product download [--force] [--auth <auth>] [--base-url <base-url>] [--version <version>] [--branch <branch>] manifest_url product_dir
Options  
--help display usage information
--force get the data again, even if it's already present locally.
--auth use specific auth flow for oauth2 (see examples; default: pkce).
--base-url location to look for product bundles manifest inside GCS.
--version filter on products of . The version number is in the format of a.b.c.d. e.g. 19.20240302.2.1. If this value is not passed in, the version will be defaulted to version of ffx tool itself.
--branch filter on products of . The branch is either in the form of f (e.g. f18) or LATEST. This option is exclusive with version option.

Examples

Sample invocations:

    // Download core.vim3 based on current ffx version. Note it will download
    // the latest version of the date section.
    ffx product download core.vim3 ~/local_pb

    // Download core.vim3 with version 19.20240302.2.1
    ffx product download core.vim3 ~/local_pb --version 19.20240302.2.1

    // Download core.vim3 for latest version of f18
    ffx product download core.vim3 ~/local_pb --branch f18 --force

    Auth flow choices for --auth include:

      `--auth no-auth` do not use auth.
      `--auth pkce` to use PKCE auth flow (requires GUI browser).
      `--auth device-experimental` to use device flow.
      `--auth ` run tool at given path which will print an access
        token to stdout and exit 0.
      `--auth default` let the tool decide which auth flow to use.

get-artifacts

Get the paths of a group of artifacts inside a Product Bundle.


Usage:  ffx product get-artifacts -g <artifacts-group> [-r] [product_bundle]
Options  
--help display usage information
-g, --artifacts-group select what group of artifacts to list. One of flash, emu, update, bootloader
-r, --relative-path return relative path or not

get-image-path

Get the path of an image inside a Product Bundle based on type and slot.


Usage:  ffx product get-image-path [--slot <slot>] [--image-type <image-type>] [-b <bootloader>] [-r] [product_bundle]
Options  
--help display usage information
--slot the slot where image will be located in. Valid slots are A,B,R.
--image-type the type of image. Supported types are fvm, fxfs, qemu-kernel, vbmeta, zbi.
-b, --bootloader the type of bootloader.
-r, --relative-path return relative path or not

get-repository

Get the info of repository inside a Product Bundle.


Usage:  ffx product get-repository product_bundle
Options  
--help display usage information

get-version

Get the product version of a Product Bundle.


Usage:  ffx product get-version product_bundle
Options  
--help display usage information

list

List all available products for a specific SDK version.


Usage:  ffx product list [--auth <auth>] [--base-url <base-url>] [--version <version>] [--branch <branch>]
Options  
--help display usage information
--auth use specific auth flow for oauth2 (see examples; default: pkce).
--base-url location to look for product bundles manifest inside GCS.
--version filter on products of . The version number is in the format of a.b.c.d. e.g. 19.20240302.2.1. If this value is not passed in, the version will be defaulted to version of ffx tool itself.
--branch filter on products of . The branch is either in the form of f (e.g. f18) or LATEST. This option is exclusive with version option.

Examples

Sample invocations:

    // List all product names based on current ffx version. Note it will list
    // the latest version of the date section.
    ffx product list

    // List all product names with version 19.20240302.2.1
    ffx product list --version 19.20240302.2.1

    // List all product names for latest version of f18
    ffx product list --branch f18

    Auth flow choices for --auth include:

      `--auth no-auth` do not use auth.
      `--auth pkce` to use PKCE auth flow (requires GUI browser).
      `--auth device-experimental` to use device flow.
      `--auth ` run tool at given path which will print an access
        token to stdout and exit 0.
      `--auth default` let the tool decide which auth flow to use.

lookup

Retrieve image data.


Usage:  ffx product lookup [--auth <auth>] [--base-url <base-url>] name version
Options  
--help display usage information
--auth use specific auth flow for oauth2 (see examples; default: pkce).
--base-url where to look for product bundles manifest.

Examples

Auth flow choices for --auth include:
  `--auth oob` to use Out-of-Band auth (deprecated).
  `--auth pkce` to use PKCE auth flow (requires GUI browser).
  `--auth ` run tool at given path which will print an access token to stdout and exit 0.

show

Display a list of details from within a product bundle.


Usage:  ffx product show [--devices] [--device <device>] product_bundle_path
Options  
--help display usage information
--devices list the virtual devices linked to this product bundle.
--device print the details of a virtual device linked to this product bundle.

profile

Profile run-time information from various subsystems


Usage:  ffx profile [subcommand...]
Options  
--help display usage information
Subcommands  
cpu Query CPU-related information
gpu Access GPU usage information
heapdump Profile and dump heap memory usage
memory Query memory related information
network Access network activity information
power Access power-related information
temperature Access temperature-related information

cpu

Query CPU-related information


Usage:  ffx profile cpu [subcommand...]
Options  
--help display usage information
Subcommands  
load Collect and print CPU usage data for the specified time frame, or instruct the metrics-logger component to record the CPU usage data to Inspect, Trace, and/or syslog.

load

Collect and print CPU usage data for the specified time frame, or instruct the metrics-logger component to record the CPU usage data to Inspect, Trace, and/or syslog.


Usage:  ffx profile cpu load [-d <duration>] [subcommand...]
Options  
--help display usage information
-d, --duration duration over which to measure and print the CPU load
Subcommands  
start Start logging on the target
stop Stop logging on the target

Examples

1) To measure the CPU load over a two second duration:

    $ ffx profile cpu load --duration 2s

    The measured CPU load from each core is printed in the following format:

        CPU 0: 0.66%
        CPU 1: 1.56%
        CPU 2: 0.83%
        CPU 3: 0.71%
        Total: 3.76%

    The valid range for each CPU load is \[0-100]%. The "Total" value represents the summation of the load percentages of all CPU cores and is valid in the range \[0-100*\[NUM_CPU]]%.

2) To log CPU load every 500 ms indefinitely:

    $ ffx profile cpu load start --interval 500ms

    Logged samples will be available via iquery under core/metrics-logger and via tracing in the `metrics_logger` category.

3) To log CPU load every 1 second for 30 seconds with output-to-syslog enabled:

    $ ffx profile cpu load start --interval 1s -d 30s --output-to-syslog

    Logged samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the `metrics_logger` category.

Notes

  • Please specify a duration for immediate load display, or alternatively, utilize the start/stop subcommand to instruct the metrics-logger component to record the CPU usage data to Inspect, Trace,and/or syslog.
If the metrics-logger component is not available to the target, add --with //src/power/metrics-logger to fx set.
start

Start logging on the target


Usage:  ffx profile cpu load start -s <interval> [--output-to-syslog] [-d <duration>]
Options  
--help display usage information
-s, --interval interval for logging the CPU load
--output-to-syslog toggle for logging CPU loads to syslog
-d, --duration duration for which to log; if omitted, logging will continue indefinitely
stop

Stop logging on the target


Usage:  ffx profile cpu load stop
Options  
--help display usage information

gpu

Access GPU usage information


Usage:  ffx profile gpu [subcommand...]
Options  
--help display usage information
Subcommands  
usage Controls the metrics-logger component to log gpu usage. Logged samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.

usage

Controls the metrics-logger component to log gpu usage. Logged samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.


Usage:  ffx profile gpu usage [subcommand...]
Options  
--help display usage information
Subcommands  
start Start logging on the target
stop Stop logging on the target

Examples

To poll gpu usage every 500 ms indefinitely:

    $ ffx profile gpu usage start --interval 500ms

To poll gpu driver every 1 second for 30 seconds with output-to-syslog enabled:

    $ ffx profile gpu usage start --interval 1s -d 30s --output-to-syslog

Notes

  • If the metrics-logger component is not available to the target, then this command will not work
properly. Add --with //src/power/metrics-logger to fx set.
start

Start logging on the target


Usage:  ffx profile gpu usage start -s <interval> [--output-to-syslog] [-d <duration>]
Options  
--help display usage information
-s, --interval interval for polling the GPU driver
--output-to-syslog toggle for logging samples to syslog
-d, --duration duration for which to log; if omitted, logging will continue indefinitely
stop

Stop logging on the target


Usage:  ffx profile gpu usage stop
Options  
--help display usage information

heapdump

Profile and dump heap memory usage


Usage:  ffx profile heapdump [subcommand...]
Options  
--help display usage information
Subcommands  
download Download stored snapshot
list List stored snapshots
snapshot Snapshot current heap memory usage

download

Download stored snapshot


Usage:  ffx profile heapdump download [--collector <collector>] --snapshot-id <snapshot-id> [--with-tags] --output-file <output-file>
Options  
--help display usage information
--collector moniker of the collector to be queried (default: autodetect)
--snapshot-id snapshot ID to be downloaded
--with-tags write per-block metadata (as tags) in the protobuf file
--output-file output protobuf file

list

List stored snapshots


Usage:  ffx profile heapdump list [--collector <collector>] [--by-name <by-name>] [--by-koid <by-koid>]
Options  
--help display usage information
--collector moniker of the collector to be queried (default: autodetect)
--by-name select process by name
--by-koid select process by koid

snapshot

Snapshot current heap memory usage


Usage:  ffx profile heapdump snapshot [--collector <collector>] [--by-name <by-name>] [--by-koid <by-koid>] --output-file <output-file> [--with-tags] [--output-contents-dir <output-contents-dir>]
Options  
--help display usage information
--collector moniker of the collector to be queried (default: autodetect)
--by-name select process by name
--by-koid select process by koid
--output-file output protobuf file
--with-tags write per-block metadata (as tags) in the protobuf file
--output-contents-dir optional directory to dump each blocks' contents into

memory

Query memory related information


Usage:  ffx profile memory [--debug-json] [--process-koids <process-koids...>] [--process-names <process-names...>] [--interval <interval>] [--buckets] [--undigested] [--csv] [--exact-sizes] [subcommand...]
Options  
--help display usage information
--debug-json outputs the json returned by memory_monitor. For debug purposes only, no garantee is made on the stability of the output of this command.
--process-koids filters by process koids. Repeatable flag.
--process-names filters by process names (exact match). Repeatable flag.
--interval repeats the command at the given interval (in seconds) until terminated.
--buckets prints a bucketized digest of the memory usage.
--undigested displays the detailed view of only the undigested memory (memory not part of any bucket) instead of the full memory.
--csv outputs csv that for every process shows the device uptime in seconds, the process koid, the process name, and the private, scale, and total memory usage. This option is not supported with other output options like --machine.
--exact-sizes outputs the exact byte sizes, as opposed to a human-friendly format. Does not impact machine oriented outputs, such as CSV and JSON outputs.
Subcommands  
components Components.
signal Signals userspace clients with specified memory pressure level. Clients can use this command to test their response to memory pressure. Does not affect the real memory pressure level on the system, or trigger any kernel reclamation tasks.

components

Components.


Usage:  ffx profile memory components [--stdin-input] [--debug-json]
Options  
--help display usage information
--stdin-input loads the unprocessed memory information as json from stdin.
--debug-json outputs the unprocessed memory information from the device as json.

signal

Signals userspace clients with specified memory pressure level. Clients can use this command to test their response to memory pressure. Does not affect the real memory pressure level on the system, or trigger any kernel reclamation tasks.


Usage:  ffx profile memory signal level
Options  
--help display usage information

network

Access network activity information


Usage:  ffx profile network [subcommand...]
Options  
--help display usage information
Subcommands  
activity Controls the metrics-logger component to log network activity. Logged samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.

activity

Controls the metrics-logger component to log network activity. Logged samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.


Usage:  ffx profile network activity [subcommand...]
Options  
--help display usage information
Subcommands  
start Start logging on the target
stop Stop logging on the target

Examples

To poll network activity every 500 ms indefinitely:

    $ ffx profile network activity start --interval 500ms

To poll network activity every 1 second for 30 seconds with output-to-syslog enabled:

    $ ffx profile network activity start --interval 1s -d 30s --output-to-syslog

Notes

  • If the metrics-logger component is not available to the target, then this command will not work
properly. Add --with //src/power/metrics-logger to fx set.
start

Start logging on the target


Usage:  ffx profile network activity start -s <interval> [--output-to-syslog] [-d <duration>]
Options  
--help display usage information
-s, --interval interval for polling the network activity
--output-to-syslog toggle for logging samples to syslog
-d, --duration duration for which to log; if omitted, logging will continue indefinitely
stop

Stop logging on the target


Usage:  ffx profile network activity stop
Options  
--help display usage information

power

Access power-related information


Usage:  ffx profile power [subcommand...]
Options  
--help display usage information
Subcommands  
logger Controls the metrics-logger component to log power. Logged power samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.

logger

Controls the metrics-logger component to log power. Logged power samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.


Usage:  ffx profile power logger [subcommand...]
Options  
--help display usage information
Subcommands  
start Start logging on the target
stop Stop logging on the target

Examples

To poll power sensor every 500 ms indefinitely:

    $ ffx profile power logger start --sampling-interval 500ms

To poll power sensor every 500 ms and summarize statistics every 1 second for 30 seconds with output-samples-to-syslog and output-stats-to-syslog enabled:

    $ ffx profile power logger start --sampling-interval 500ms --statistics-interval 1s --output-stats-to-syslog --output-samples-to-syslog -d 30s

Notes

  • If the metrics-logger component is not available to the target, then this command will not work
properly. Add --with //src/power/metrics-logger to fx set.
start

Start logging on the target


Usage:  ffx profile power logger start [-l <statistics-interval>] -s <sampling-interval> [--output-samples-to-syslog] [--output-stats-to-syslog] [-d <duration>]
Options  
--help display usage information
-l, --statistics-interval interval for summarizing statistics; if omitted, statistics is disabled
-s, --sampling-interval interval for polling the sensor
--output-samples-to-syslog toggle for logging samples to syslog
--output-stats-to-syslog toggle for logging statistics to syslog
-d, --duration duration for which to log; if omitted, logging will continue indefinitely
stop

Stop logging on the target


Usage:  ffx profile power logger stop
Options  
--help display usage information

temperature

Access temperature-related information


Usage:  ffx profile temperature [subcommand...]
Options  
--help display usage information
Subcommands  
logger Controls the metrics-logger component to log temperature. Logged temperature samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.

logger

Controls the metrics-logger component to log temperature. Logged temperature samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.


Usage:  ffx profile temperature logger [subcommand...]
Options  
--help display usage information
Subcommands  
start Start logging on the target
stop Stop logging on the target

Examples

To poll temperature sensor every 500 ms indefinitely:

    $ ffx profile temperature logger start --sampling-interval 500ms

To poll temperature sensor every 500 ms and summarize statistics every 1 second for 30 seconds with output-samples-to-syslog and output-stats-to-syslog enabled:

    $ ffx profile temperature logger start --sampling-interval 500ms --statistics-interval 1s --output-stats-to-syslog --output-samples-to-syslog -d 30s

Notes

  • If the metrics-logger component is not available to the target, then this command will not work
properly. Add --with //src/power/metrics-logger to fx set.
start

Start logging on the target


Usage:  ffx profile temperature logger start [-l <statistics-interval>] -s <sampling-interval> [--output-samples-to-syslog] [--output-stats-to-syslog] [-d <duration>]
Options  
--help display usage information
-l, --statistics-interval interval for summarizing statistics; if omitted, statistics is disabled
-s, --sampling-interval interval for polling the sensor
--output-samples-to-syslog toggle for logging samples to syslog
--output-stats-to-syslog toggle for logging statistics to syslog
-d, --duration duration for which to log; if omitted, logging will continue indefinitely
stop

Stop logging on the target


Usage:  ffx profile temperature logger stop
Options  
--help display usage information

profiler

Interact with the profiling subsystem.


Usage:  ffx profiler [subcommand...]
Options  
--help display usage information
Subcommands  
attach Profile a running task or component
launch Record a profile.
symbolize Symbolize a previously-recorded profile that was not symbolized.

attach

Profile a running task or component


Usage:  ffx profiler attach [--url <url>] [--buffer-size-mb <buffer-size-mb>] [--moniker <moniker>] [--pids <pids...>] [--tids <tids...>] [--job-ids <job-ids...>] [--system-wide] [--duration <duration>] [--output <output>] [--print-stats] [--symbolize <symbolize>] [--pprof-conversion <pprof-conversion>] [--sample-period-us <sample-period-us>] [--color-output <color-output>]
Options  
--help display usage information
--url url of a component to profile. If there is no matching component, wait for one to appear.
--buffer-size-mb buffer size in MiB to profile. Specifies the amount of memory allocated for storing profiling information.
--moniker moniker of a component to profile. If there is no matching component, the profiler will
--pids pids to profile
--tids tids to profile
--job-ids jobs to profile
--system-wide profile everything running on the system. Equivalent to profiling the root job and everything running under it.
--duration how long to profiler for. If unspecified, will interactively wait until is pressed.
--output name of output trace file. Defaults to profile.pb.
--print-stats print stats about how the profiling session went
--symbolize if false, output the raw sample file instead of attempting to symbolize it
--pprof-conversion if false, output the raw symbolized sample file instead of attempting to convert to the pprof format. Ignored if --symbolize is false.
--sample-period-us how frequently to take a sample
--color-output if true, include color codes in output. Defaults to true if terminal output is detected, else false

launch

Record a profile.


Usage:  ffx profiler launch --url <url> [--buffer-size-mb <buffer-size-mb>] [--moniker <moniker>] [--duration <duration>] [--output <output>] [--print-stats] [--symbolize <symbolize>] [--pprof-conversion <pprof-conversion>] [--sample-period-us <sample-period-us>] [--test] [--test-filters <test-filters...>] [--color-output <color-output>]
Options  
--help display usage information
--url url of a component to launch and profile
--buffer-size-mb buffer size in MiB to profile. Specifies the amount of memory allocated for storing profiling information.
--moniker moniker of a component to attach to and profile. If specified in combination with --url, will attempt to launch the component at the given moniker.
--duration how long in seconds to profile for. If unspecified, will interactively wait until is pressed.
--output name of output trace file. Defaults to profile.pb.
--print-stats print stats about how the profiling session went
--symbolize if false, output the raw sample file instead of attempting to symbolize it
--pprof-conversion if false, output the raw symbolized sample file instead of attempting to convert to the pprof format. Ignored if --symbolize is false.
--sample-period-us how frequently to take a sample. This is the time interval between samples, in microseconds. The default is 10,000 microseconds (10 ms).
--test the package being launched is a test to be launched via test_manager
--test-filters test case filters to apply to profiled tests
--color-output if true, include color codes in output. Defaults to true if terminal output is detected, else false

symbolize

Symbolize a previously-recorded profile that was not symbolized.


Usage:  ffx profiler symbolize [--pprof-conversion <pprof-conversion>] input output
Options  
--help display usage information
--pprof-conversion if false, output the raw symbolized sample file instead of attempting to convert to the pprof format.

repository

Inspect and manage package repositories


Usage:  ffx repository [subcommand...]
Options  
--help display usage information
Subcommands  
add Make the daemon aware of specific product bundle repositories
add-from-pm Make the daemon aware of a specific pm-built repository
create Create a repository.
default Manage the default repository
list List all repositories
package List the packages inside a repository
publish Publish packages.
remove Remove repository from deamon server configuration.
serve serve repositories and product bundles, and register repositories to device
server Inspect and manage the repository server

add

Make the daemon aware of specific product bundle repositories


Usage:  ffx repository add [-p <prefix>] product_bundle_dir
Options  
--help display usage information
-p, --prefix repositories will have the prefix NAME. Defaults to devhost.

add-from-pm

Make the daemon aware of a specific pm-built repository


Usage:  ffx repository add-from-pm [-r <repository>] [--alias <alias...>] pm_repo_path
Options  
--help display usage information
-r, --repository repositories will be named NAME. Defaults to devhost.
--alias alias this repository to these names when this repository is registered on a target.

create

Create a repository.


Usage:  ffx repository create [--time-versioning] [--keys <keys>] repo_path
Options  
--help display usage information
--time-versioning set repository version based on the current time rather than monotonically increasing version
--keys path to the repository keys directory. Default to generate keys at 'repo_path'/keys.

default

Manage the default repository


Usage:  ffx repository default [subcommand...]
Options  
--help display usage information
Subcommands  
get Get the default configured repository
set Set the default repository
unset Clears the default configured repository

Examples

For one-off overrides for the default use `--repository` option:

    $ ffx repository  --repository  ...

Or use the `--config` option:

    $ ffx --config repository.default= repository

Notes

  • Manages the default configured repository for all operations. The default
repository is designated by a * next to the name. This is an alias for the
repository.default configuration key.

get

Get the default configured repository


Usage:  ffx repository default get
Options  
--help display usage information

Notes

  • Returns the default configured repository from the 'User Configuration'.
Returns an empty string if no default is configured.

set

Set the default repository


Usage:  ffx repository default set [-l <level>] [-b <build-dir>] name
Options  
--help display usage information
-l, --level config level, such as 'user', 'build', or 'global'
-b, --build-dir optional directory to associate the provided build config

Examples

To set the default repository:

   $ ffx repository default set 

To set the 'repository.default` key at the global configuration:

   $ ffx repository default set -l global 

To specify a default repository for a specific build directory:

   $ ffx repository default set -l build -b ~/fuchsia/out

Notes

  • Sets the repository.default configuration key. By default sets the key in
the 'User Configuration'. Can be used in conjuction with ffx repository list
to list the names of the discovered repositorys.

After setting the default repository, ffx repository list will mark the default with a * in the output list.

unset

Clears the default configured repository


Usage:  ffx repository default unset [-l <level>] [-b <build-dir>]
Options  
--help display usage information
-l, --level config level, such as 'user', 'build', or 'global'
-b, --build-dir optional directory to associate the provided build config

Examples

To clear the default repository:

    $ ffx repository default unset

To clear the `repository.default` key from global configuration:

    $ ffx repository default unset -l global

To specify a specific build directory:

    $ ffx repository default unset -l build -b ~/fuchsia/out

Notes

  • Clears the repository.default configuration key. By default clears the
'User Configuration'. Returns a warning if the key is already empty.

list

List all repositories


Usage:  ffx repository list
Options  
--help display usage information

package

List the packages inside a repository


Usage:  ffx repository package [subcommand...]
Options  
--help display usage information
Subcommands  
extract-archive Extract a package archive from the repository
list Inspect and manage package repositories
show Inspect content of a package

extract-archive

Extract a package archive from the repository


Usage:  ffx repository package extract-archive -o <out> [-r <repository>] [-p <port>] package
Options  
--help display usage information
-o, --out output path for the extracted archive.
-r, --repository extract package from this repository.
-p, --port repository server port number. Required disambiguate multiple repositories with the same name.

list

Inspect and manage package repositories


Usage:  ffx repository package list [-r <repository>] [-p <port>] [--full-hash] [--include-components <include-components>]
Options  
--help display usage information
-r, --repository list packages from this repository.
-p, --port repository server port number. Required needed to disambiguate multiple repositories with the same name.
--full-hash if true, package hashes will be displayed in full (i.e. not truncated).
--include-components toggle whether components in each package will be fetched and shown in the output table

show

Inspect content of a package


Usage:  ffx repository package show [-r <repository>] [-p <port>] [--full-hash] [--include-subpackages <include-subpackages>] package
Options  
--help display usage information
-r, --repository list package contents from this repository.
-p, --port repository server port number. Required to disambiguate multiple repositories with the same name.
--full-hash if true, package hashes will be displayed in full (i.e. not truncated).
--include-subpackages if true, show contents of subpackages contained in the package.

publish

Publish packages.


Usage:  ffx repository publish [--signing-keys <signing-keys>] [--trusted-keys <trusted-keys>] [--trusted-root <trusted-root>] [--package <package...>] [--package-list <package-list...>] [--package-archive <package-archive...>] [--product-bundle <product-bundle...>] [--time-versioning] [--metadata-current-time <metadata-current-time>] [--refresh-root] [--clean] [--depfile <depfile>] [--copy-mode <copy-mode>] [--delivery-blob-type <delivery-blob-type>] [--watch] [--ignore-missing-packages] [--blob-manifest <blob-manifest>] [--blob-repo-dir <blob-repo-dir>] repo_path
Options  
--help display usage information
--signing-keys path to the keys used to sign metadata, but not trust for key rotation
--trusted-keys path to the keys used to sign and trust metadata (default repository keys/ directory)
--trusted-root path to the initial trusted root metadata (default is to use 1.root.json from the repository)
--package path to a package manifest
--package-list path to a packages list manifest
--package-archive path to a package archive
--product-bundle path to a product bundle
--time-versioning set repository version based on time rather than monotonically increasing version
--metadata-current-time the RFC 3339 time used to see if metadata has expired, and when new metadata should expire (default uses the current time)
--refresh-root generate a new root metadata along side all the other metadata
--clean clean the repository so only new publications remain
--depfile produce a depfile file
--copy-mode mode used to copy blobs to repository. Either 'copy', 'copy-overwrite', or 'hard-link' (default 'copy').
--delivery-blob-type the type of delivery blob to generate (default: type 1)
--watch republish packages on file change
--ignore-missing-packages ignore if package paths do not exist
--blob-manifest path to write the blob manifest to
--blob-repo-dir path to the blobs directory (default '$repo_path/repository/blobs')

remove

Remove repository from deamon server configuration.


Usage:  ffx repository remove [--all] [name]
Options  
--help display usage information
--all remove all repositories

serve

serve repositories and product bundles, and register repositories to device


Usage:  ffx repository serve [-r <repository>] [--trusted-root <trusted-root>] [--address <address>] [--repo-path <repo-path>] [--product-bundle <product-bundle>] [--alias <alias...>] [--storage-type <storage-type>] [--alias-conflict-mode <alias-conflict-mode>] [--port-path <port-path>] [--no-device] [--refresh-metadata] [--auto-publish <auto-publish>]
Options  
--help display usage information
-r, --repository register this repository. Default is devhost.
--trusted-root path to the root metadata that was used to sign the repository TUF metadata. This establishes the root of trust for this repository. If the TUF metadata was not signed by this root metadata, running this command will result in an error. Default is to use 1.root.json from the repository.
--address address on which to serve the repository. Note that this can be either IPV4 or IPV6. For example, [::]:8083 or 127.0.0.1:8083 Default is \[::]:8083.
--repo-path location of the package repo. Default is given by the build directory obtained from the ffx context.
--product-bundle location of product bundle.
--alias set up a rewrite rule mapping each alias host to the repository identified by name.
--storage-type enable persisting this repository across reboots. Default is Ephemeral.
--alias-conflict-mode resolution mechanism when alias registrations conflict. Must be either error-out or replace. Default is replace.
--port-path location to write server port information to, in case port dynamically instantiated.
--no-device if true, will not register repositories to device. Default is false.
--refresh-metadata refresh repository metadata during startup. Note that this is not necessary if package-tool runs in the background taking care of it, e.g. as part of fx serve. Default is false.
--auto-publish auto publish packages listed in the given manifest. This uses time based versioning when publishing and ignores missing packages. The manifest is a json file a single member "content", which contains a list named "manifest". The list is a list of package manifests, relative paths are relative to the directory of the auto-publish manifest.

server

Inspect and manage the repository server


Usage:  ffx repository server [subcommand...]
Options  
--help display usage information
Subcommands  
list Retrieves the status of the repository server. If server is running will also return socket address. Note that all repositories under ffx repository list will be running as subpaths at the returned address.
start Starts the repository server. Note that all repositories listed from ffx repository list will be started as subpaths.
status Retrieves the status of the repository server. If server is running will also return socket address. Note that all repositories under ffx repository list will be running as subpaths at the returned address.
stop Stops the repository server

list

Retrieves the status of the repository server. If server is running will also return socket address. Note that all repositories under ffx repository list will be running as subpaths at the returned address.


Usage:  ffx repository server list [--full] [--name <name...>]
Options  
--help display usage information
--full long version of output.
--name limit output to provided name. This option can appear multiple times

start

Starts the repository server. Note that all repositories listed from ffx repository list will be started as subpaths.


Usage:  ffx repository server start [--address <address>] [--background] [--daemon] [--foreground] [-r <repository>] [--trusted-root <trusted-root>] [--repo-path <repo-path>] [--product-bundle <product-bundle>] [--alias <alias...>] [--storage-type <storage-type>] [--alias-conflict-mode <alias-conflict-mode>] [--port-path <port-path>] [--no-device] [--refresh-metadata] [--auto-publish <auto-publish>]
Options  
--help display usage information
--address address on which to start the repository. Note that this can be either IPV4 or IPV6. For example, [::]:8083 or 127.0.0.1:8083 Default is read from config repository.server.listen or \[::]:8083 if not set.
--background run server as a background process. This is mutually exclusive with --daemon and --foreground.
--daemon run server in as part of the ffx daemon. This is the default mode. This switch is mutually exclusive with --background and --foreground.
--foreground run server as a foreground process. This is mutually exclusive with --daemon and --background.
-r, --repository register this repository. Default is devhost.
--trusted-root path to the root metadata that was used to sign the repository TUF metadata. This establishes the root of trust for this repository. If the TUF metadata was not signed by this root metadata, running this command will result in an error. Default is to use 1.root.json from the repository.
--repo-path location of the package repo. Default is given by the build directory obtained from the ffx context.
--product-bundle location of product bundle.
--alias set up a rewrite rule mapping each alias host to the repository identified by name.
--storage-type enable persisting this repository across reboots. Default is Ephemeral.
--alias-conflict-mode resolution mechanism when alias registrations conflict. Must be either error-out or replace. Default is replace.
--port-path location to write server port information to, in case port dynamically instantiated.
--no-device if true, will not register repositories to device. Default is false.
--refresh-metadata refresh repository metadata during startup. Note that this is not necessary if package-tool runs in the background taking care of it, e.g. as part of fx serve. Default is false.
--auto-publish auto publish packages listed in the given manifest. This uses time based versioning when publishing and ignores missing packages. The manifest is a json file a single member "content", which contains a list named "manifest". The list is a list of package manifests, relative paths are relative to the directory of the auto-publish manifest.

status

Retrieves the status of the repository server. If server is running will also return socket address. Note that all repositories under ffx repository list will be running as subpaths at the returned address.


Usage:  ffx repository server status
Options  
--help display usage information

stop

Stops the repository server


Usage:  ffx repository server stop [--all] [--product-bundle <product-bundle>] [-p <port>] [name]
Options  
--help display usage information
--all stop all repository servers.
--product-bundle stop servers serving the product bundle location.
-p, --port repository server port number. Required to disambiguate multiple repositories with the same name.

scrutiny

Audit the security of Fuchsia


Usage:  ffx scrutiny [subcommand...]
Options  
--help display usage information
Subcommands  
extract Extracts common Fuchsia file types
list Lists properties about build artifacts
shell Launch the scrutiny shell
verify Verify the build

extract

Extracts common Fuchsia file types


Usage:  ffx scrutiny extract [subcommand...]
Options  
--help display usage information
Subcommands  
blobfs Extracts a Blobfs block file
fvm Extracts a FVM file
package Extracts a Fuchsia package from a Url
structured-config Extracts the structured configuration from Fuchsia build artifacts.
zbi Extracts the Zircon Boot Image

blobfs

Extracts a Blobfs block file


Usage:  ffx scrutiny extract blobfs input output
Options  
--help display usage information

Examples

To extract a Blobfs block file:

        $ffx scrutiny extract blobfs blob.blk /tmp/blobs

Notes

  • Extracts a blobfs block file to a specific directory.

fvm

Extracts a FVM file


Usage:  ffx scrutiny extract fvm input output
Options  
--help display usage information

Examples

To extract a FVM file:

        $ffx scrutiny extract fvm fvm.blk /tmp/fvm

Notes

  • Extracts a FVM to a specific directory.

package

Extracts a Fuchsia package from a Url


Usage:  ffx scrutiny extract package --product-bundle <product-bundle> --url <url> --output <output> [--recovery]
Options  
--help display usage information
--product-bundle a path to a product bundle that contains the package.
--url the package url.
--output the location to write the output artifacts.
--recovery build scrutiny model based on recovery-mode build artifacts.

Examples

To extract a Fuchsia package from a url:

        $ ffx scrutiny extract package --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle --url fuchsia-pkg://fuchsia.com/foo --output /tmp/foo

Notes

  • Extracts a package to a specific directory.

structured-config

Extracts the structured configuration from Fuchsia build artifacts.


Usage:  ffx scrutiny extract structured-config --product-bundle <product-bundle> --build-path <build-path> --depfile <depfile> --output <output> [--recovery]
Options  
--help display usage information
--product-bundle path to a product bundle.
--build-path path to the build directory which is used to rebase the paths in the depfile.
--depfile path to a depfile that should be written for build integration
--output path to file to which to write the extracted configuration.
--recovery build scrutiny model based on recovery-mode build artifacts.

Notes

  • Extracts structured configuration

zbi

Extracts the Zircon Boot Image


Usage:  ffx scrutiny extract zbi input output
Options  
--help display usage information

Examples

To extract a Zircon Boot Image:

        $ffx scrutiny extract zbi foo.zbi /tmp/foo

Notes

  • Extracts a ZBI to a specific directory.

list

Lists properties about build artifacts


Usage:  ffx scrutiny list [subcommand...]
Options  
--help display usage information
Subcommands  
components Lists all the components in the build
package Lists all the files in a package
packages Lists all the packages in the build

components

Lists all the components in the build


Usage:  ffx scrutiny list components --product-bundle <product-bundle> [--recovery]
Options  
--help display usage information
--product-bundle path to a product bundle.
--recovery build scrutiny model based on recovery-mode build artifacts.

Examples

To list all the components in the build:

        $ffx scrutiny list components --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle

Notes

  • Lists all the components in the build in a json format.

package

Lists all the files in a package


Usage:  ffx scrutiny list package --product-bundle <product-bundle> --url <url> [--recovery]
Options  
--help display usage information
--product-bundle path to a product bundle.
--url fuchsia url to the package.
--recovery build scrutiny model based on recovery-mode build artifacts.

Examples

To list all the files in a package:

        $ ffx scrutiny list package --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle --url fuchsia-pkg://fuchsia.com/foo

Notes

  • Lists all the package contents in json format.

packages

Lists all the packages in the build


Usage:  ffx scrutiny list packages --product-bundle <product-bundle> [--recovery]
Options  
--help display usage information
--product-bundle path to a product bundle.
--recovery build scrutiny model based on recovery-mode build artifacts.

Examples

To list all the packages in the build:

        $ffx scrutiny list packages --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle

Notes

  • Lists all the packages in the build in a json format.

shell

Launch the scrutiny shell


Usage:  ffx scrutiny shell command
Options  
--help display usage information

Examples

To run commands directly:

    $ ffx scrutiny shell "tool.blobfs.extract --input  --output "

Notes

  • Runs a command in scrutiny. Deprecated for the more specific scrutiny methods.

verify

Verify the build


Usage:  ffx scrutiny verify [--depfile <depfile>] [--stamp <stamp>] [--tmp-dir <tmp-dir>] [--recovery] [subcommand...]
Options  
--help display usage information
--depfile path to depfile that gathers dependencies during execution.
--stamp path to stamp file to write to if and only if verification succeeds.
--tmp-dir path to directory to use for temporary files.
--recovery build scrutiny model based on recovery-mode build artifacts.
Subcommands  
bootfs Verifies list of files in bootfs inside a product bundle against a golden file
component-resolvers Verifies that component configured to use custom component resolvers are permitted by an allowlist.
kernel-cmdline Verifies that kernel cmdline arguments match golden files.
pre-signing Runs assorted checks to ensure a build is okay to sign
route-sources Verifies that routes to designated components are routed from designated sources.
routes Verifies capability routes in the component tree
static-pkgs Check the static packages extracted from the ZBI against golden files
structured-config Verifies component configuration according to configured assertions.

bootfs

Verifies list of files in bootfs inside a product bundle against a golden file


Usage:  ffx scrutiny verify bootfs --product-bundle <product-bundle> [--golden <golden...>] [--golden-packages <golden-packages...>]
Options  
--help display usage information
--product-bundle absolute or working directory-relative path to a product bundle.
--golden absolute or working directory-relative path(s) to golden file(s) for verifying bootfs paths.
--golden-packages absolute or working directory-relative path(s) to golden file(s) for verifying bootfs packages.

Examples

To verify bootfs on your current build:

    $ ffx scrutiny verify bootfs \
        --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle \
        --golden /path/to/goldens/product.txt \
        --golden /path/to/goldens/board.txt

Notes

  • Verifies all file paths in bootfs.

component-resolvers

Verifies that component configured to use custom component resolvers are permitted by an allowlist.


Usage:  ffx scrutiny verify component-resolvers --product-bundle <product-bundle> --allowlist <allowlist>
Options  
--help display usage information
--product-bundle absolute or working directory-relative path to a product bundle.
--allowlist absolute or working directory-relative path to allowlist file that specifies which components may use particular custom component resolvers.

Examples

To verify component resolvers on your current eng build:

    $ ffx scrutiny verify component-resolvers --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle --allowlist ../../src/security/policy/component_resolvers_policy.json5

Notes

  • Verifies all components that use a custom component resolver.

kernel-cmdline

Verifies that kernel cmdline arguments match golden files.


Usage:  ffx scrutiny verify kernel-cmdline --product-bundle <product-bundle> [--golden <golden...>]
Options  
--help display usage information
--product-bundle absolute or working directory-relative path to a product bundle.
--golden absolute or working directory-relative path(s) to golden files to compare against during verification.

Examples

To verify kernel cmdline arguments on your current build:

    $ ffx scrutiny verify kernel-cmdline \
        --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle \
        --golden path/to/golden

pre-signing

Runs assorted checks to ensure a build is okay to sign


Usage:  ffx scrutiny verify pre-signing --policy <policy> --product-bundle <product-bundle> --golden-files-dir <golden-files-dir>
Options  
--help display usage information
--policy path to a signing validation policy file
--product-bundle path to the product bundle for the build to validate
--golden-files-dir path to the directory containing golden files for pre_signing

Examples

To run the pre signing checks against a build:

    $ ffx scrutiny verify pre-signing \
        --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle \
        --policy path/to/policy_file \
        --golden_files_dir path/to/goldens/dir

route-sources

Verifies that routes to designated components are routed from designated sources.


Usage:  ffx scrutiny verify route-sources --product-bundle <product-bundle> --config <config>
Options  
--help display usage information
--product-bundle absolute or working directory-relative path to a product bundle.
--config absolute or working directory-relative path to configuration file that specifies components and their expected route sources.

Examples

To verify route sources according to a configuration file on your current build:

    $ ffx scrutiny verify route-sources
        --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle \
        --config path/to/verify_route_sources/product.board.json5

routes

Verifies capability routes in the component tree


Usage:  ffx scrutiny verify routes [--capability-type <capability-type...>] [--response-level <response-level>] --product-bundle <product-bundle> [--component-tree-config <component-tree-config>]
Options  
--help display usage information
--capability-type capability types to verify.
--response-level response level to report from routes scrutiny plugin.
--product-bundle absolute or working directory-relative path to a product bundle.
--component-tree-config absolute or working path-relative path to component tree configuration file that affects how component tree data is gathered.

Examples

To verify routes on your current build:

    $ ffx scrutiny verify routes \
        --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle

static-pkgs

Check the static packages extracted from the ZBI against golden files


Usage:  ffx scrutiny verify static-pkgs --product-bundle <product-bundle> [--golden <golden...>]
Options  
--help display usage information
--product-bundle path to a product bundle.
--golden path(s) to golden file(s) used to verify routes.

Examples

To verify static packages on your current build:

        $ ffx scrutiny verify static-pkgs --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle --golden path/to/golden

structured-config

Verifies component configuration according to configured assertions.


Usage:  ffx scrutiny verify structured-config --policy <policy> --product-bundle <product-bundle>
Options  
--help display usage information
--policy absolute or working directory-relative path to a policy file for structured configuration
--product-bundle path to a product bundle.

sdk

Modify or query the installed SDKs


Usage:  ffx sdk [subcommand...]
Options  
--help display usage information
Subcommands  
populate-path Populates the given path with symlinks to the fuchsha-sdk-run tool to run project-specific sdk tools
run Run a host tool from the active sdk
set Set sdk-related configuration options
version Retrieve the version of the current SDK

populate-path

Populates the given path with symlinks to the fuchsha-sdk-run tool to run project-specific sdk tools


Usage:  ffx sdk populate-path path
Options  
--help display usage information

run

Run a host tool from the active sdk


Usage:  ffx sdk run name args
Options  
--help display usage information

set

Set sdk-related configuration options


Usage:  ffx sdk set [subcommand...]
Options  
--help display usage information
Subcommands  
root Sets the path to the root of the preferred SDK

root

Sets the path to the root of the preferred SDK


Usage:  ffx sdk set root path
Options  
--help display usage information

version

Retrieve the version of the current SDK


Usage:  ffx sdk version
Options  
--help display usage information

session

Control the session component.


Usage:  ffx session [subcommand...]
Options  
--help display usage information
Subcommands  
add Add an element to the current session.
drop-power-lease Drop the power lease reserved for the current session component.
launch Launch a session component.
remove Remove an element from the current session.
restart Restart the current session component.
show Show information about the current session
start Start the default session component.
stop Stop the session component.

Notes

  • See https://fuchsia.dev/fuchsia-src/glossary#session-component.

add

Add an element to the current session.

If the --persist option is used, the package should be in the base or cache package set as otherwise it might fail to launch after a reboot.


Usage:  ffx session add [--interactive] [--persist] [--name <name>] url
Options  
--help display usage information
--interactive pass to keep element alive until command exits
--persist pass to have the element persist over reboots
--name name for the element which defaults to random if not specified

Examples

To add the `bouncing_ball.cm` component as an element:

    $ ffx session add fuchsia-pkg://fuchsia.com/bouncing_ball#meta/bouncing_ball.cm

drop-power-lease

Drop the power lease reserved for the current session component.


Usage:  ffx session drop-power-lease
Options  
--help display usage information

Notes

  • This command is useful for testing system suspension. If the session component has not taken the lease, then the lease will be dropped. If no other components on the system hold a power lease on the execution state, this will suspend the system.

launch

Launch a session component.


Usage:  ffx session launch [--config <config...>] url
Options  
--help display usage information
--config provide additional configuration capabilities to the component being run. Specified in the format fully.qualified.Name=VALUE where fully.qualified.Name is the name of the configuration capability, and VALUE is a JSON string which can be resolved as the correct type of configuration value.

Examples

To launch the `hello-world-session.cm` component as a session:

    $ ffx session launch fuchsia-pkg://fuchsia.com/hello-world-session#meta/hello-world-session.cm

remove

Remove an element from the current session.

Persistent elements will be removed permanently. Any persistent storage used by elements will not be removed.


Usage:  ffx session remove name
Options  
--help display usage information

restart

Restart the current session component.


Usage:  ffx session restart
Options  
--help display usage information

Notes

  • Destroys the existing session component, if any, then creates and starts a new component with the same URL. Requires that a session componentwas previously launched.

show

Show information about the current session


Usage:  ffx session show
Options  
--help display usage information

start

Start the default session component.


Usage:  ffx session start
Options  
--help display usage information

Notes

  • The default session component is specified by the URL session_urlin session_manager's structured configuration.

stop

Stop the session component.


Usage:  ffx session stop
Options  
--help display usage information

setui

Modify and query settings.


Usage:  ffx setui [subcommand...]
Options  
--help display usage information
Subcommands  
accessibility watch or set accessibility settings
audio get or set audio settings
display get or set display settings
do_not_disturb get or set DnD settings
factory_reset get or set factory reset settings
input get or set input settings
intl get or set internationalization settings
keyboard get or set keyboard settings
light get or set light settings
night_mode get or set night mode settings
privacy get or set privacy settings
setup get or set setup settings

accessibility

watch or set accessibility settings


Usage:  ffx setui accessibility [subcommand...]
Options  
--help display usage information
Subcommands  
add-caption add caption options, the configuration for which sources get closed caption and how they look
set set other accessibility options
watch watch current accessibility settings

add-caption

add caption options, the configuration for which sources get closed caption and how they look


Usage:  ffx setui accessibility add-caption [-m <for-media>] [-t <for-tts>] [-w <window-color>] [-b <background-color>] [-f <font-family>] [-c <font-color>] [-r <relative-size>] [-e <char-edge-style>]
Options  
--help display usage information
-m, --for-media enable closed captions for media sources of audio
-t, --for-tts enable closed captions for Text-To-Speech sources of audio
-w, --window-color border color used around the closed captions window. Valid options are red, green, and blue
-b, --background-color border color used around the closed captions window. Valid options are red, green, and blue
-f, --font-family font family for captions as specified by 47 CFR §79.102(k). Valid options are unknown, monospaced_serif, proportional_serif, monospaced_sans_serif, proportional_sans_serif, casual, cursive, and small_capitals
-c, --font-color color of the closed caption text. Valid options are red, green, and blue
-r, --relative-size size of closed captions text relative to the default captions size, specified in the range [0.5, 2] as per 47 CFR §79.103(c)(4)
-e, --char-edge-style edge style for fonts as specified in 47 CFR §79.103(c)(7). Valid options are none, drop_shadow, raised, depressed, outline

set

set other accessibility options


Usage:  ffx setui accessibility set [-a <audio-description>] [-s <screen-reader>] [-i <color-inversion>] [-m <enable-magnification>] [-c <color-correction>]
Options  
--help display usage information
-a, --audio-description when set to 'true', will turn on an audio track for videos that includes a description of what is occurring in the video
-s, --screen-reader when set to 'true', will read aloud elements of the screen selected by the user
-i, --color-inversion when set to 'true', will invert the colors on the screen
-m, --enable-magnification when set to 'true', will interpret triple-taps on the touchscreen as a command to zoom in
-c, --color-correction configures the type of color-blindness to correct for. Valid options are none, protanomaly, deuteranomaly, and tritanomaly

watch

watch current accessibility settings


Usage:  ffx setui accessibility watch
Options  
--help display usage information

audio

get or set audio settings


Usage:  ffx setui audio [-t <stream>] [-s <source>] [-l <level>] [-v <volume-muted>]
Options  
--help display usage information
-t, --stream which stream should be modified. Valid options are background, media, interruption, system_agent, and communication
-s, --source which source is changing the stream. Valid options are user, system, and system_with_feedback
-l, --level the volume level specified as a float in the range [0, 1]
-v, --volume-muted whether or not the volume is muted

display

get or set display settings


Usage:  ffx setui display [subcommand...]
Options  
--help display usage information
Subcommands  
get Get the current display settings.
set Sets display settings.
watch Get the current display settings and watch for changes.

get

Get the current display settings.


Usage:  ffx setui display get [-f <field>]
Options  
--help display usage information
-f, --field choose which display settings field value to return, valid options are auto and brightness

set

Sets display settings.


Usage:  ffx setui display set [-b <brightness>] [-o <auto-brightness-level>] [-a <auto-brightness>] [-m <low-light-mode>] [-t <theme>] [-s <screen-enabled>]
Options  
--help display usage information
-b, --brightness the brightness value specified as a float in the range [0, 1]
-o, --auto-brightness-level the brightness values used to control auto brightness as a float in the range [0, 1]
-a, --auto-brightness when set to 'true', enables auto brightness
-m, --low-light-mode which low light mode setting to enable. Valid options are enable, disable, and disable_immediately
-t, --theme which theme to set for the device. Valid options are default, dark, light, darkauto, and lightauto
-s, --screen-enabled when set to 'true' the screen is enabled

watch

Get the current display settings and watch for changes.


Usage:  ffx setui display watch
Options  
--help display usage information

do_not_disturb

get or set DnD settings


Usage:  ffx setui do_not_disturb [-u <user-dnd>] [-n <night-mode-dnd>]
Options  
--help display usage information
-u, --user-dnd when set to 'true', allows the device to enter do not disturb mode
-n, --night-mode-dnd when set to 'true', forces the device into do not disturb mode

factory_reset

get or set factory reset settings


Usage:  ffx setui factory_reset [-l <is-local-reset-allowed>]
Options  
--help display usage information
-l, --is-local-reset-allowed when set to 'true', factory reset can be performed on the device

input

get or set input settings


Usage:  ffx setui input [-t <device-type>] [-n <name>] [-s <state>]
Options  
--help display usage information
-t, --device-type the type of input device. Valid options are camera and microphone
-n, --name the name of the device. Must be unique within a device type
-s, --state the device state flags, pass a comma separated string of the values available, active, muted, disabled and error. E.g. "-s available,active"

intl

get or set internationalization settings


Usage:  ffx setui intl [-z <time-zone>] [-u <temperature-unit>] [-l <locales...>] [-h <hour-cycle>] [--clear-locales]
Options  
--help display usage information
-z, --time-zone a valid timezone matching the data available at https://www.iana.org/time-zones
-u, --temperature-unit the unit to use for temperature. Valid options are celsius and fahrenheit
-l, --locales list of locales, separated by spaces, formatted by Unicode BCP-47 Locale Identifier, e.g. en-us
-h, --hour-cycle the hour cycle to use. Valid options are h11 for 12-hour clock with 0:10 am after midnight, h12 for 12-hour clock with 12:10am after midnight, h23 for 24-hour clock with 0:10 after midnight, and h24 for 24-hour clock with 24:10 after midnight
--clear-locales if set, this flag will set locales as an empty list. Overrides the locales arguments

keyboard

get or set keyboard settings


Usage:  ffx setui keyboard [-k <keymap>] [-d <autorepeat-delay>] [-p <autorepeat-period>]
Options  
--help display usage information
-k, --keymap keymap selection for the keyboard. Valid options are - UsQwerty - FrAzerty - UsDvorak - UsColemak
-d, --autorepeat-delay delay value of autorepeat values for the keyboard. Values should be a positive integer plus an SI time unit. Valid units are s, ms. If this value and autorepeat_period are zero, the autorepeat field of KeyboardSettings will be cleaned as None.
-p, --autorepeat-period period value of autorepeat values for the keyboard. Values should be a positive integer plus an SI time unit. Valid units are s, ms. If this value and autorepeat_delay are zero, the autorepeat field of KeyboardSettings will be cleaned as None.

light

get or set light settings


Usage:  ffx setui light [-n <name>] [-s <simple...>] [-b <brightness...>] [-r <rgb...>]
Options  
--help display usage information
-n, --name name of a light group to set values for. Required if setting the value of a light group
-s, --simple repeated parameter for a list of simple on/off values to set for a light group.
-b, --brightness repeated parameter for a list of floating point brightness values in the range [0, 1] for a light group
-r, --rgb repeated parameter for a list of RGB values to set for a light group. Values should be in the range [0, 1] and specified as a comma-separated list of the red, green, and blue components. Ex. 0.1,0.4,0.23

night_mode

get or set night mode settings


Usage:  ffx setui night_mode [-n <night-mode-enabled>]
Options  
--help display usage information
-n, --night-mode-enabled when 'true', enables night mode

privacy

get or set privacy settings


Usage:  ffx setui privacy [-u <user-data-sharing-consent>]
Options  
--help display usage information
-u, --user-data-sharing-consent when 'true', is considered to be user giving consent to have their data shared with product owner, e.g. for metrics collection and crash reporting

setup

get or set setup settings


Usage:  ffx setui setup [-i <interfaces>]
Options  
--help display usage information
-i, --interfaces a supported group of interfaces, specified as a comma-delimited string of the valid values eth and wifi, e.g. "-i eth,wifi" or "-i wifi"

starnix

Control starnix containers


Usage:  ffx starnix [subcommand...]
Options  
--help display usage information
Subcommands  
adb Bridge from host adb to adbd running inside starnix
console Attach a console to a starnix container
vmo Return all processes that have references to a file backed by a vmo with koid

adb

Bridge from host adb to adbd running inside starnix


Usage:  ffx starnix adb [--adb <adb>] [subcommand...]
Options  
--help display usage information
--adb path to the adb client command
Subcommands  
connect directly connect the local adb server to an adbd instance running on the target.
proxy Bridge from host adb to adbd running inside starnix

Examples

ffx starnix adb proxy

connect

directly connect the local adb server to an adbd instance running on the target.


Usage:  ffx starnix adb connect
Options  
--help display usage information

proxy

Bridge from host adb to adbd running inside starnix


Usage:  ffx starnix adb proxy [-m <moniker>] [-p <port>] [--no-autoconnect]
Options  
--help display usage information
-m, --moniker the moniker of the container running adbd (defaults to looking for a container in the current session)
-p, --port which port to serve the adb server on
--no-autoconnect disable automatically running "adb connect"

console

Attach a console to a starnix container


Usage:  ffx starnix console [-m <moniker>] [-e <env...>] argv
Options  
--help display usage information
-m, --moniker the moniker of the container in which to create the console (defaults to looking for a container in the current session)
-e, --env environment variables to pass to the program.

Examples

ffx starnix console \[-e ENV=VAL -e ...] program \[argument ...]

vmo

Return all processes that have references to a file backed by a vmo with koid


Usage:  ffx starnix vmo -k <koid>
Options  
--help display usage information
-k, --koid koid of the vmo to search for references to.

Examples

ffx starnix vmo -k 123456

storage

Manage Fuchsia Filesystems.


Usage:  ffx storage [subcommand...]
Options  
--help display usage information
Subcommands  
fxfs Interact with fxfs instances.

fxfs

Interact with fxfs instances.


Usage:  ffx storage fxfs [subcommand...]
Options  
--help display usage information
Subcommands  
compact Forces a (blocking) compaction of all layer files.
delete_profile Deletes a profile from a named unlocked volume. Fails during active profile record or replay.
stop_profile Blocks while stopping all profile recording and replay activity.

compact

Forces a (blocking) compaction of all layer files.


Usage:  ffx storage fxfs compact
Options  
--help display usage information

Examples

ffx storage fxfs compact

delete_profile

Deletes a profile from a named unlocked volume. Fails during active profile record or replay.


Usage:  ffx storage fxfs delete_profile volume profile
Options  
--help display usage information

Examples

ffx storage fxfs delete_profile

stop_profile

Blocks while stopping all profile recording and replay activity.


Usage:  ffx storage fxfs stop_profile
Options  
--help display usage information

Examples

ffx storage fxfs stop_profile

target

Interact with a target device or emulator


Usage:  ffx target [subcommand...]
Options  
--help display usage information
Subcommands  
add Make the daemon aware of a specific target
bootloader Communicates with the bootloader
clear-preferred-ssh-address Clears a previously configured SSH address
default Manage the default target
echo run echo test against the target
flash Flash an image to a target device
get-ssh-address Get the target's ssh address
get-time Returns the current time in the system monotonic clock.
list List all targets
off Powers off a target
reboot Reboots a target
remove Make the daemon forget a specific target
repository Interact with target repository registration
screenshot Takes a screenshot of the target
set-preferred-ssh-address Sets the preferred SSH address
show Display relevant information for the target
snapshot Takes a snapshot of the target's state
ssh SSH to a target device
update Update base system software on target
wait Wait until able to establish a remote control connection to the target.

Notes

  • The target subcommand contains various commands for target management
and interaction.

Typically, this is the entry workflow for users, allowing for target discovery and provisioning before moving on to component or session workflows once the system is up and running on the target.

Most of the commands depend on the RCS (Remote Control Service) on the target.

add

Make the daemon aware of a specific target


Usage:  ffx target add [-n] addr
Options  
--help display usage information
-n, --nowait do not wait for a connection to be verified on the Fuchsia device.

Examples

To add a remote target forwarded via ssh:

    $ ffx target add 127.0.0.1:8022

Or to add a target using its IPV6:

    $ ffx target add fe80::32fd:38ff:fea8:a00a

Notes

  • Manually add a target based on its IP address. The command accepts IPV4
or IPV6 addresses, including a port number: <addr> = <ip addr:port>.

Typically, the daemon automatically discovers targets as they come online. However, manually adding a target allows for specifying a port number or address, often used for remote workflows.

This command will attempt to connect to the target in order to verify that RCS can be used, allowing for typical FFX related workflows. If you do not wish to use this, then you can run use the --nowait flag to return immediately. This can be useful for debugging connection issues.

If you send SIGINT (Ctrl-C) to the command before the connection to the target is verified, the target will be removed. If RCS cannot be connected to (e.g. some connectivity error is encountered), the target will also be removed.

bootloader

Communicates with the bootloader


Usage:  ffx target bootloader [-m <manifest>] [-p <product>] [-b <product-bundle>] [--skip-verify] [subcommand...]
Options  
--help display usage information
-m, --manifest path to flashing manifest or zip file containing images and manifest
-p, --product product entry in manifest - defaults to fuchsia
-b, --product-bundle optional product bundle name
--skip-verify skip hardware verification. This is dangerous, please be sure the images you are using match the device
Subcommands  
boot RAM boots a fastboot target.
info Prints fastboot variables for target.
lock Locks a fastboot target.
unlock Unlocks a fastboot target.

boot

RAM boots a fastboot target.


Usage:  ffx target bootloader boot [-z <zbi>] [-v <vbmeta>] [-s <slot>]
Options  
--help display usage information
-z, --zbi optional zbi image file path to use
-v, --vbmeta optional vbmeta image file path to use
-s, --slot slot corresponding to partitions in the flash manifest -

only used if zbi and vbmeta files are not present

info

Prints fastboot variables for target.


Usage:  ffx target bootloader info
Options  
--help display usage information

lock

Locks a fastboot target.


Usage:  ffx target bootloader lock
Options  
--help display usage information

unlock

Unlocks a fastboot target.


Usage:  ffx target bootloader unlock [-c <cred>] [--force]
Options  
--help display usage information
-c, --cred optional path to credential file to use to unlock the device
--force skips the warning message that this command is dangerous

clear-preferred-ssh-address

Clears a previously configured SSH address


Usage:  ffx target clear-preferred-ssh-address
Options  
--help display usage information

Notes

  • Clears a preferred SSH address that was set using the
set-preferred-ssh-address command on the default target. Executing this command
severs any existing connection to the target and establishes a new connection.
The newly selected address is chosen using the standard address selection
logic.

default

Manage the default target


Usage:  ffx target default [subcommand...]
Options  
--help display usage information
Subcommands  
get Get the default configured target
set Set the default target
unset Clears the default configured target

Examples

For one-off overrides for the default use `--target` option:

    $ ffx --target  

Or use the `--config` option:

    $ ffx --config target.default=

Notes

  • Manages the default configured target for all operations. The default
target is designated by a * next to the name. This is an alias for the
target.default configuration key.

get

Get the default configured target


Usage:  ffx target default get [-l <level>] [-b <build-dir>]
Options  
--help display usage information
-l, --level config level, such as 'user', 'build', or 'global' - defaults to searching all levels
-b, --build-dir optional directory to associate the provided build config

Notes

  • Returns the default configured target from the 'User Configuration'.
Returns an empty string if no default is configured.

set

Set the default target


Usage:  ffx target default set [-l <level>] [-b <build-dir>] nodename
Options  
--help display usage information
-l, --level config level, such as 'user', 'build', or 'global'
-b, --build-dir optional directory to associate the provided build config

Examples

To set the default target:

   $ ffx target default set 

To set the 'target.default` key at the global configuration:

   $ ffx target default set -l global 

To specify a default target for a specific build directory:

   $ ffx target default set -l build -b ~/fuchsia/out

Notes

  • Sets the target.default configuration key. By default sets the key in
the 'User Configuration'. Can be used in conjuction with ffx target list
to list the names of the discovered targets.

After setting the default target, ffx target list will mark the default with a * in the output list.

unset

Clears the default configured target


Usage:  ffx target default unset [-l <level>] [-b <build-dir>]
Options  
--help display usage information
-l, --level config level, such as 'user', 'build', or 'global'
-b, --build-dir optional directory to associate the provided build config

Examples

To clear the default target:

    $ ffx target default unset

To clear the `target.default` key from global configuration:

    $ ffx target default unset -l global

To specify a specific build directory:

    $ ffx target default unset -l build -b ~/fuchsia/out

Notes

  • Clears the target.default configuration key. By default clears the
'User Configuration'. Returns a warning if the key is already empty.

echo

run echo test against the target


Usage:  ffx target echo [--repeat] [text]
Options  
--help display usage information
--repeat run the echo test repeatedly until the command is killed

flash

Flash an image to a target device


Usage:  ffx target flash [-p <product>] [-b <product-bundle>] [-m <manifest>] [--oem-stage <oem-stage...>] [--authorized-keys <authorized-keys>] [--no-bootloader-reboot] [--skip-verify] [--timeout-rate <timeout-rate>] [--min-timeout-secs <min-timeout-secs>] [manifest_path]
Options  
--help display usage information
-p, --product product entry in manifest - defaults to fuchsia
-b, --product-bundle optional product bundle name
-m, --manifest optional manifest path
--oem-stage oem staged file - can be supplied multiple times
--authorized-keys path to authorized keys file - will default to the value configured for ssh.pub key in ffx config. If the file does not exist, it will be created.
--no-bootloader-reboot the device should not reboot after bootloader images are flashed
--skip-verify skip hardware verification. This is dangerous, please be sure the images you are flashing match the device
--timeout-rate flash timeout rate in mb/second.
--min-timeout-secs minimum timeout in seconds to wait while flashing per-partition

Examples

To flash a specific image:

    $ ffx target flash --manifest $(fx get-build-dir)/flash.json --product fuchsia

To include SSH keys as well:

    $ ffx target flash
    --authorized-keys ~/fuchsia/.ssh/authorized_keys
    $(fx get-build-dir)/flash.json
    --product fuchsia

Notes

  • Flashes an image to a target device using the fastboot protocol.
Requires a specific  file and  name as an input.

This is only applicable to a physical device and not an emulator target. The target device is typically connected via a micro-USB connection to the host system.

The format is a JSON file generated when building a fuchsia and can be found in the build output directory.

The --oem-stage option can be supplied multiple times for several OEM files. The format expects a single OEM command to execute after staging the given file.

The format for the --oem-stage parameter is a comma separated pair: ','

get-ssh-address

Get the target's ssh address


Usage:  ffx target get-ssh-address [-t <timeout>]
Options  
--help display usage information
-t, --timeout the timeout in seconds [default = 1.0]

Notes

  • Return the SSH address of the default target defined in the
target.default key. By default this comes from the 'User Configuration'.

The command takes a value in seconds with a default of 1.0 and overrides the value in the target.interaction.timeout key.

Errors  
1 Timeout while getting ssh address
2 Unable to get ssh address from target

get-time

Returns the current time in the system monotonic clock. This is the number of nanoseconds since the system was powered on. It does not always reset on reboot and does not adjust during sleep, and thus should not be used as a reliable source of uptime.

See https://fuchsia.dev/reference/syscalls/clock_get_monotonic


Usage:  ffx target get-time [-b]
Options  
--help display usage information
-b, --boot if true, return boot time

Examples

To get the target time:

    $ ffx target get-time

list

List all targets


Usage:  ffx target list [-f <format>] [--no-ipv4] [--no-ipv6] [--no-probe] [--no-mdns] [--no-usb] [nodename]
Options  
--help display usage information
-f, --format determines the output format for the list operation
--no-ipv4 do not return IPv4 addresses
--no-ipv6 do not return IPv6 addresses
--no-probe do not connect to targets (local discovery only)
--no-mdns do not do mDNS discovery (local discovery only)
--no-usb do not do USB discovery (local discovery only)

Examples

To list targets in short form:

    $ ffx target list --format s
    fe80::4415:3606:fb52:e2bc%zx-f80ff974f283 pecan-guru-clerk-rhyme

To list targets with only their addresses:

    $ ffx target list --format a
    fe80::4415:3606:fb52:e2bc%zx-f80ff974f283

Notes

  • List all targets that the daemon currently has in memory. This includes
manually added targets. The daemon also proactively discovers targets as
they come online. Use ffx target list to always get the latest list
of targets. Targets are sorted by name.

The default target is marked with a '*' next to the node name. The table has the following columns:

NAME = The name of the target.
SERIAL = The serial number of the target.
TYPE = The product type of the target.
STATE = The high-level state of the target.
ADDRS/IP = The discovered and known addresses of the target.
RCS = Indicates if the Remote Control Service is running on the target.

The NAME column shows the target's advertised name. When the target is in early boot state such as fastboot, the NAME column may be <unknown> with a STATE being fastboot and a SERIAL attribute.

By default, the list command outputs in a tabular format. To override the format, pass --format and can take the following options: 'simple' , 'tabular|table|tab', 'addresses|addrs|addr', 'name-only', 'json|JSON' or in short form 's', 't', 'a', 'n', 'j'.

By default, Zedboot discovery is disabled. To enable discovery of Zedboot targets run:

$ ffx config set discovery.zedboot.enabled true

Errors  
2 If a nodename is supplied, an error code of 2 will be returned if the nodename cannot be resolved

off

Powers off a target


Usage:  ffx target off
Options  
--help display usage information

Notes

  • Power off a target. Uses the 'fuchsia.hardware.power.statecontrol.Admin'
FIDL API to send the power off command.

'fuchsia.hardware.power.statecontrol.Admin' is exposed by the 'power_manager' component. To verify that the target exposes this service, ffx component select or ffx component knock can be used.

Errors  
1 Timeout while powering off target.

reboot

Reboots a target


Usage:  ffx target reboot [-b] [-r]
Options  
--help display usage information
-b, --bootloader reboot to bootloader
-r, --recovery reboot to recovery

Notes

  • Reboot a target. Uses the 'fuchsia.hardware.power.statecontrol.Admin'
FIDL API to send the reboot command.

By default, target boots fully. This behavior can be overrided by passing in either --bootloader or --recovery to boot into the bootloader or recovery, respectively.

'fuchsia.hardware.power.statecontrol.Admin' is exposed by the 'power_manager' component. To verify that the target exposes this service, ffx component select or ffx component knock can be used.

Errors  
1 Timeout while powering off target.

remove

Make the daemon forget a specific target


Usage:  ffx target remove [--all] [name_or_addr]
Options  
--help display usage information
--all remove all manually added targets

Examples

To remove a target by its target name:

    $ ffx target remove correct-horse-battery-staple

Or to remove a target using its IP address:

    $ ffx target remove fe80::32fd:38ff:fea8:a00a

Notes

  • IP addresses are matched by their full string representation.
for best results, copy the exact address from ffx target list.

repository

Interact with target repository registration


Usage:  ffx target repository [subcommand...]
Options  
--help display usage information
Subcommands  
deregister Make the target forget a specific repository
list List all the repositories on a target
register Make the target aware of a specific repository

Notes

  • The `repository` subcommand contains various commands for repository management
and interaction on targets.

Most of the commands depend on the RCS (Remote Control Service) on the target.

deregister

Make the target forget a specific repository


Usage:  ffx target repository deregister [-r <repository>] [-p <port>]
Options  
--help display usage information
-r, --repository remove the repository named name from the target, rather than the default.
-p, --port repository server port number. Required to disambiguate multiple repositories with the same name.

list

List all the repositories on a target


Usage:  ffx target repository list
Options  
--help display usage information

register

Make the target aware of a specific repository


Usage:  ffx target repository register [-r <repository>] [-p <port>] [--storage-type <storage-type>] [--alias <alias...>] [--alias-conflict-mode <alias-conflict-mode>]
Options  
--help display usage information
-r, --repository register this repository, rather than the default.
-p, --port repository server port number. Required to disambiguate multiple repositories with the same name.
--storage-type enable persisting this repository across reboots.
--alias set up a rewrite rule mapping each alias host to to the repository identified by name.
--alias-conflict-mode resolution mechanism when alias registrations conflict. Must be either error-out or replace. Default is replace.

screenshot

Takes a screenshot of the target


Usage:  ffx target screenshot [-d <dir>] [--format <format>]
Options  
--help display usage information
-d, --dir override the default directory where the screenshot will be saved
--format screenshot format. If no value is provided bgra will be used. 
    Accepted values: bgra, rgba, png

Examples

Store the target's screenshot in a directory:

    $ ffx target screenshot -d .
    Exported ./screenshot

Notes

  • This command connects to a running target to take its screenshot.
The --dir can be supplied to override the default
screenshot saving location /tmp/screenshot/YYYYMMDD_HHMMSS/.
The --format can be supplied to override the default format png.
Accepted format values: bgra, rgba, png.
The screenshot file name is screenshot.<format>.

set-preferred-ssh-address

Sets the preferred SSH address


Usage:  ffx target set-preferred-ssh-address addr
Options  
--help display usage information

Examples

To set a preferred IPv4 SSH address:

    $ ffx target set-preferred-ssh-address 127.0.0.1

Or to set a preferred IPv6 SSH address:

    $ ffx target set-preferred-ssh-addres fe80::32fd:38ff:fea8:a00a%qemu

If provided, the scope may either correspond to the numerical ID or the
interface name.

Notes

  • Manually set the preferred SSH address on the default target. If
successful, then any existing connection to the target is severed and a new
connection is established. The specified address is not persisted across daemon
version changes or restarts.

show

Display relevant information for the target


Usage:  ffx target show [--desc] [--label]
Options  
--help display usage information
--desc display descriptions of entries
--label display label of entries

Notes

  • Displays a detailed information about the target.

The default output is intended for a human reader. This output can be decorated with machine readable labels (--label) and descriptions of each field (--desc).

The 'label' fields in the machine readable output (--json) will remain stable across software updates and is not localized (compare to 'title' which may change or be localized). The 'value' field will be one of: 'null', 'bool', 'string', or a list of strings.

Errors  
1 Timeout retrieving target information.

snapshot

Takes a snapshot of the target's state


Usage:  ffx target snapshot [-d <dir>] [--dump-annotations]
Options  
--help display usage information
-d, --dir valid directory where the snapshot will be stored
--dump-annotations print annotations without capturing the snapshot, ignores dir flag

Examples

Store the target's snapshot in the current directory:

    $ ffx target snapshot -d .
    Exported ./snapshot.zip

Notes

  • This command connects to a running target to acquire its snapshot, which contains
useful debugging information about the target. The --dir can be supplied to override the default
snapshot directory /tmp/snapshots/YYYYMMDD_HHMMSS/.

Snapshot contents: - Build information and annotations - Kernel and system logs - Inspect data

ssh

SSH to a target device


Usage:  ffx target ssh [--sshconfig <sshconfig>] [command...]
Options  
--help display usage information
--sshconfig path to the custom ssh config file to use.

Examples

To ssh to a specific device:

    $ ffx -t fuchsia-EEEE-NNNN target ssh

To ssh and run a command:

    $ ffx target ssh 'echo $USER'

update

Update base system software on target


Usage:  ffx target update [subcommand...]
Options  
--help display usage information
Subcommands  
channel View and manage update channels
check-now Check and perform the system update operation
force-install Trigger the system updater manually

Notes

  • This command interfaces with system update services on the target.

channel

View and manage update channels


Usage:  ffx target update channel [subcommand...]
Options  
--help display usage information
Subcommands  
get-current Return the currently configured update channel
get-next Return the next or target update channel
list List the known update channels
set Sets the update channel

Notes

  • Channel management commands and operations. Interfaces directly with
the 'fuchsia.update.channelcontrol.ChannelControl' service on the target
system.
get-current

Return the currently configured update channel


Usage:  ffx target update channel get-current
Options  
--help display usage information

Notes

  • For developer product configurations, this is by default 'devhost'.
Errors  
1 Timeout while getting update channel.
get-next

Return the next or target update channel


Usage:  ffx target update channel get-next
Options  
--help display usage information

Notes

  • Returns the next or target channel. This differs from get when the
next successful update changes the configured update channel on the
system.
Errors  
1 Timeout while getting update channel.
list

List the known update channels


Usage:  ffx target update channel list
Options  
--help display usage information

Notes

  • This lists all the known next or target update channels on the system.

Returns an empty list if no other update channels are configured.

Errors  
1 Timeout while getting list of update channel.
set

Sets the update channel


Usage:  ffx target update channel set channel
Options  
--help display usage information

Examples

To list all the known update channels:

    $ ffx target update channel list

Then, use a valid channel from the list:

    $ ffx target update channel set

Notes

  • Sets the next or target update channel on the device. When paired with
ffx target update check-now, ensures the update is check against the
next or target channel. When the update is successful, next or target
channel becomes the current channel.

Use ffx target update channel list to list known system update channels.

Errors  
1 Timeout while setting update channel.

check-now

Check and perform the system update operation


Usage:  ffx target update check-now [--service-initiated] [--monitor] [--product-bundle] [product_bundle_path]
Options  
--help display usage information
--service-initiated the update check was initiated by a service, in the background.
--monitor monitor for state update.
--product-bundle use the product bundle to use as the source of the update.

Examples

To check for update and monitor progress:

    $ ffx target update check-now --monitor

Notes

  • Triggers an update check operation and performs the update if available.
Interfaces using the 'fuchsia.update Manager' protocol with the system
update service on the target.

The command takes in an optional --monitor switch to watch the progress of the update. The output is displayed in stdout.

The command also takes an optional --service-initiated switch to indicate a separate service has initiated a check for update.

force-install

Trigger the system updater manually


Usage:  ffx target update force-install [--reboot <reboot>] [--product-bundle] update_pkg_url [product_bundle_path]
Options  
--help display usage information
--reboot automatically trigger a reboot into the new system
--product-bundle use the product bundle to use as the source of the update.

Examples

With a known update package URL, trigger an update and reboot:

    $ ffx target update force-install fuchsia-pkg://fuchsia.com/update

Don't reboot after update:

    $ ffx target update force-install
    fuchsia-pkg://fuchsia.com/update
    --reboot false

Notes

  • Directly invoke the system updater to install the provided update,
bypassing any update checks.

Interfaces using the 'fuchsia.update.installer' protocol to update the system. Requires an in the following format:

fuchsia-pkg://fuchsia.com/update

Takes an optional --reboot <true|false> to trigger a system reboot after update has been successfully applied.

wait

Wait until able to establish a remote control connection to the target.


Usage:  ffx target wait [-t <timeout>] [-d]
Options  
--help display usage information
-t, --timeout the timeout in seconds [default = 120]. A value of 0 implies no timeout.
-d, --down wait for target to go down
Errors  
1 Timeout while getting ssh address

target-package

Interact with the target's packaging system


Usage:  ffx target-package [subcommand...]
Options  
--help display usage information
Subcommands  
explore Resolves a package and then spawns a shell with said package loaded into the namespace at /pkg.

explore

Resolves a package and then spawns a shell with said package loaded into the namespace at /pkg.


Usage:  ffx target-package explore [--subpackage <subpackage...>] [--tools <tools...>] [-c <command>] [--fuchsia-pkg-resolver <fuchsia-pkg-resolver>] url
Options  
--help display usage information
--subpackage the chain of subpackages, if any, of url to resolve, in resolution order. If subpackages is not empty, the package directory of the final subpackage will be loaded into the shell's namespace at /pkg.
--tools list of URLs of tools packages to include in the shell environment. the PATH variable will be updated to include binaries from these tools packages. repeat --tools url for each package to be included. The path preference is given by command line order.
-c, --command execute a command instead of reading from stdin. the exit code of the command will be forwarded to the host.
--fuchsia-pkg-resolver the resolver to use when resolving package URLs with scheme "fuchsia-pkg". Possible values are "base" and "full". Defaults to "full".

Examples

To explore the update package interactively:

> ffx target-package explore 'fuchsia-pkg://fuchsia.com/update'
$ ls
svc
pkg
$ exit
Connection to terminal closed

To run a command directly from the command line:
> ffx target package explore 'fuchsia-pkg://fuchsia.com/update' -c 'printenv'
PATH=/.dash/tools/debug-dash-launcher
PWD=/

Notes

  • The environment contains the following directories:
  • /.dash User-added and built-in dash tools
  • /pkg The package directory of the resolved package
  • /svc Protocols required by the dash shell

If additional binaries are provided via --tools, they will be loaded into .dash/tools// The path is set so that they can be run by name. The path preference is in the command line order of the --tools arguments, ending with the built-in dash tools (/.dash/tools/debug-dash-launcher).

--tools URLs may be package or binary URLs. Note that collisions can occur if different URLs have the same package and binary names. An error, NonUniqueBinaryName, is returned if a binary name collision occurs.

test

Run test suite


Usage:  ffx test [subcommand...]
Options  
--help display usage information
Subcommands  
early-boot-profile Manage early boot profiles
list-cases List test suite cases
run Execute test suites on a target device

Notes

  • Run tests or inspect output from a previous test run.

early-boot-profile

Manage early boot profiles


Usage:  ffx test early-boot-profile --output-directory <output-directory>
Options  
--help display usage information
--output-directory output early boot profile to the specified directory. The produced output is in the format described in https://fuchsia.dev/fuchsia-src/reference/platform-spec/testing/test-output-format

list-cases

List test suite cases


Usage:  ffx test list-cases [--realm <realm>] test_url
Options  
--help display usage information
--realm the realm to enumerate the test in. This field is optional and takes the form: /path/to/realm:test_collection.

Notes

  • Lists the set of test cases available in a test suite

run

Execute test suites on a target device


Usage:  ffx test run [--test-file <test-file>] [-t <timeout>] [--test-filter <test-filter...>] [--realm <realm>] [--run-disabled] [--parallel <parallel>] [--max-severity-logs <max-severity-logs>] [--continue-on-timeout] [--stop-after-failures <stop-after-failures>] [--count <count>] [--experimental-parallel-execution <experimental-parallel-execution>] [--break-on-failure] [--filter-ansi] [--min-severity-logs <min-severity-logs...>] [--show-full-moniker-in-logs] [--output-directory <output-directory>] [--disable-output-directory] [--no-exception-channel] [test_args...]
Options  
--help display usage information
--test-file read test url and options from the specified file instead of from the command line. May not be used in conjunction with test_args, --count, --test-filter, --run-disabled, --parallel, --max-severity-logs This option is currently unstable and the format of the file is subject to change. Using this option requires setting the 'test.experimental_json_input' configuration to true. For current details, see test-list.json format at https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/src/lib/testing/test_list/
-t, --timeout test suite timeout in seconds.
--test-filter test case filter. This filter will match based on glob pattern. This option may be specified multiple times. Only test cases matching at least one pattern will be run. Negative filters may be specified by prepending '-' and will exclude matching test cases.
--realm the realm to run the test in. This field is optional and takes the form: /path/to/realm:test_collection. See https://fuchsia.dev/go/components/non-hermetic-tests
--run-disabled also execute test cases that have been disabled by the test author.
--parallel maximum number of test cases to run in parallel. Defaults to a value specified by the test runner.
--max-severity-logs when set, fails tests that emit logs with a higher severity. For example, if --max-severity-logs WARN is specified, fails any test that produces an ERROR level log.
--continue-on-timeout continue running unfinished suites if a suite times out. This option is only relevant when multiple suites are run.
--stop-after-failures stop running unfinished suites after the number of provided failures has occurred. This option is only relevant when multiple suites are run.
--count number of times to run the test suite. By default run the suite 1 time.
--experimental-parallel-execution enables experimental parallel test scheduler. The provided number specifies the max number of test suites to run in parallel. If the value provided is 0, a default value will be chosen by the server implementation.
--break-on-failure enable break_on_failure for supported test runners. Any test case failure causes the test execution to stop and wait for zxdb to attach to debug the failure. When the debugger exits, the process will be released and the suite will be continued. Note: test runners may or may not have the ability to halt a test suite after it has started executing. If there isn't a way to raise an exception for a debugger to catch, the test will run and exit as normal, and will not wait for any debugger interaction.
--filter-ansi filter ANSI escape sequences from output.
--min-severity-logs set the minimum log severity printed. This modifies the minimum log severity level emitted by components during the test execution. Specify using the format #, or just (in which case the severity will apply to all components under the test, including the test component itself) with level as one of FATAL
--show-full-moniker-in-logs show the full moniker in unstructured log output.
--output-directory output test results to the specified directory. The produced output is in the format described in https://fuchsia.dev/fuchsia-src/reference/platform-spec/testing/test-output-format
--disable-output-directory disable structured output to a directory. Note structured output is disabled by default, unless --output-directory is specified. This option supported an experiment which has been removed. It is now a no-op and will soon be removed.
--no-exception-channel when set, prevents test_manager from creating exception channels that may confilict with those created by the test.

Examples

Run a test suite:
    $ ffx test run fuchsia-pkg://fuchsia.com/my_test#meta/my_test.cm

Run a test suite in system realm:
    $ ffx test run --realm /core/testing/system-tests fuchsia-pkg://fuchsia.com/my_test#meta/my_test.cm

Run a test suite and pass arguments to the suite:
    $ ffx test run fuchsia-pkg://fuchsia.com/my_test#meta/my_test.cm -- arg1 arg2

Run test suites specified in a JSON file (currently unstable):
    $ ffx test run --test-file test-list.json

Given a suite that contains the test cases 'Foo.Test1', 'Foo.Test2',
'Bar.Test1', and 'Bar.Test2':

Run test cases that start with 'Foo.' ('Foo.Test1', 'Foo.Test2'):
    $ ffx test run  --test-filter 'Foo.*'

Run test cases that do not start with 'Foo.' ('Bar.Test1', 'Bar.Test2'):
    $ ffx test run  --test-filter '-Foo.*'

Run test cases that start with 'Foo.' and do not end with 'Test1' ('Foo.Test2'):
    $ ffx test run  --test-filter 'Foo.*' --test-filter '-*.Test1'

Notes

  • Runs test suites implementing the fuchsia.test.Suite protocol.

When multiple test suites are run, either through the --count option or through --test-file, the default behavior of ffx test is: If any test suite times out, halt execution and do not attempt to run any unstarted suites. If any test suite fails for any other reason, continue to run unstarted suites.

trace

Tracing is a tool that allows you to collect, aggregate, and visualize diagnostic tracing information from both userspace processes and the Zircon kernel on a Fuchsia device.


Usage:  ffx trace [subcommand...]
Options  
--help display usage information
Subcommands  
list-categories List the target's known trace categories.
list-category-groups List the builtin and custom category groups.
list-providers List the target's trace providers.
start Record a trace.
status Gets status of all running traces.
stop Stops an active running trace.
symbolize Symbolizes the provided ordinal

Examples


\[Quick Start]:

    $ ffx trace start \[--duration  ]

This will record a trace using the default categories, which are suitable for getting a high
level overview.

This will produce a file `trace.fxt` which can be uploaded to ui.perfetto.dev to be viewed.

Notes

  • For a full tutorial, visit https://fuchsia.dev/fuchsia-src/development/sdk/ffx/record-traces

list-categories

List the target's known trace categories.


Usage:  ffx trace list-categories
Options  
--help display usage information

list-category-groups

List the builtin and custom category groups.


Usage:  ffx trace list-category-groups
Options  
--help display usage information

list-providers

List the target's trace providers.


Usage:  ffx trace list-providers
Options  
--help display usage information

start

Record a trace.


Usage:  ffx trace start [--buffering-mode <buffering-mode>] [--buffer-size <buffer-size>] [--categories <categories>] [--duration <duration>] [--output <output>] [--background] [-v] [--trigger <trigger...>] [--no-symbolize]
Options  
--help display usage information
--buffering-mode the buffering scheme to trace with. Defaults to "oneshot" oneshot: Writes to the tracing buffer until it is full, then ignores all additional trace events. circular: Writes to the tracing buffer until its is full, then new events will replace old events. streaming: Forwards tracing events to the trace manager as they arrive. Provides additional buffer space with the trade off of some overhead due to occasional ipcs to send the events to the trace manager during the trace.
--buffer-size size of per-provider trace buffer in MB. Defaults to 4.
--categories comma-separated list of categories to enable. Defaults to "#default". Run ffx config get trace.category_groups.default to see what categories are included in #default. A trailing "" may be used to indicate a prefix match. For example, "kernel" includes any category that starts with kernel. A name prefixed with # indicates a category group that will be expanded from ffx config within the plugin before being sent to trace manager. A category group can either be added to global config by editing data/config.json in the ffx trace plugin, or by using ffx config set to add/edit a user configured category group. Available category groups can be discovered by running ffx config get -s all trace.category_groups A category may be limited to a specific trace provider using a '/'. For example --categories "scenic.cm/FrameDropped" will only enable the "FrameDropped" category for the scenic.cm trace provider and no other providers. Categories and category groups may be mixed, for example, ffx trace start --categories #default,my_category Enables all the default categories as well as "my_category".
--duration duration of trace capture in seconds.
--output name of output trace file. Defaults to trace.fxt.
--background whether to run the trace in the background. Defaults to false, which means the trace will run in "interactive" mode. For a trace started in the background for a specified duration, symbolization is not done by default.
-v, --verbose increase verbosity of output on trace stop. Defaults to false. This is ignored if duration is not set. Enabling this prints stats from trace providers including the number of records dropped, wrapped buffers count, % of durable buffer used and non durable bytes written.
--trigger a trigger consists of an alert leading to an action. An alert is written into the code being traced, and an action here is what to do when the alert has happened. The list of supported actions are: 'terminate'. The expected format is ":" ex: -trigger "my_alert:terminate" This can be used with a duration, but keep in mind that this introduces a race between whether the alert leads to an action, and when the trace stops from the duration being reached. Triggers can only be used in the background outside of interactive mode.
--no-symbolize prevent symbolization of the trace file. Defaults to false. If the 'kernel:ipc' category is not included in tracing, this flag does nothing. Otherwise this flag will prevent the symbolization of the kernel IPC traces, leaving the ordinals as is in the trace. This flag is only used if tracing is manually stopped.

Examples

\[Quick Start]:

    $ ffx trace start \[--duration  ]

This will record a trace using the default categories, which are suitable for getting a high
level overview.

This will produce a file `trace.fxt` which can be uploaded to ui.perfetto.dev to be viewed.

\[Trace Various Categories]:

    $ ffx trace start --categories '#default,flatland:*,temp'

This will record a trace with all the default categories enabled, 'temp' events enabled, and any
event that starts with 'flatland:'


\[Capturing a Sporadic Occurrence]

    $ ffx trace start --buffer-size 64 --buffering-mode circular

This will run the trace with the largest available buffer size, overwriting the old events with new
ones. When the event occurs press  to stop the trace.


\[Automatically Capturing a Sporadic Occurrence with a Trigger]

This approach allows you to automatically stop the trace when the event happens, but the traced
code must already be set up to write a trigger event.

    $ ffx trace start --buffer-size 64 --buffering-mode circular --trigger ':terminate'

Notes

  • For a full tutorial, visit https://fuchsia.dev/fuchsia-src/development/sdk/ffx/record-traces

status

Gets status of all running traces.


Usage:  ffx trace status
Options  
--help display usage information

stop

Stops an active running trace.


Usage:  ffx trace stop [--output <output>] [-v] [--no-symbolize]
Options  
--help display usage information
--output name of output trace file. Relative or absolute paths are both supported. If this is not supplied (the default), then the default target will be used as the method to stop the trace.
-v, --verbose increase verbosity of command output. Defaults to false. Enabling this prints stats from trace providers including the number of records dropped, wrapped buffers count, % of durable buffer used and non durable bytes written.
--no-symbolize prevent symbolization of the trace file. Defaults to false. If the 'kernel:ipc' category is not included in tracing, this flag does nothing. Otherwise this flag will prevent the symbolization of the kernel IPC traces, leaving only the ordinals in the trace.

symbolize

Symbolizes the provided ordinal


Usage:  ffx trace symbolize [--ordinal <ordinal>] [--fxt <fxt>] [--outfile <outfile>] [--ir-path <ir-path...>]
Options  
--help display usage information
--ordinal FIDL ordinal to be symbolized.
--fxt trace file to be symbolized.
--outfile symbolized file path. Defaults to overwriting the input file.
--ir-path additional IR files to use for symbolization. Path provided must be absolute or relative to $FUCHSIA_BUILD_DIR. If not provided, only the files listed in $FUCHSIA_BUILD_DIR/all_fidl_json.txt will be checked.

triage

Analyze Logs and Inspect in snapshots to find problems.


Usage:  ffx triage [--config <config...>] [--data <data>] [--tag <tag...>] [--exclude-tag <exclude-tag...>]
Options  
--help display usage information
--config path to config file or dir
--data path to snapshot.zip or uncompressed dir
--tag adds an action tags to include
--exclude-tag adds an action tags to exclude

version

Print out ffx tool and daemon versions


Usage:  ffx version [-v]
Options  
--help display usage information
-v, --verbose if true, includes details about both ffx and the daemon

wlan

Developer tool for manipulating WLAN state.


Usage:  ffx wlan [subcommand...]
Options  
--help display usage information
Subcommands  
ap Controls WLAN AP policy API.
client Controls WLAN client policy API.
deprecated Controls to-be-deleted WLAN functionality.

ap

Controls WLAN AP policy API.


Usage:  ffx wlan ap [subcommand...]
Options  
--help display usage information
Subcommands  
listen Listens for policy AP updates
start Start an access point interface
status Provides the first available AP status update
stop Stop an access point interface
stop-all Stops all active APs

listen

Listens for policy AP updates


Usage:  ffx wlan ap listen
Options  
--help display usage information

Examples

To begin listening for AP events

    $ ffx wlan ap listen

start

Start an access point interface


Usage:  ffx wlan ap start [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
Options  
--help display usage information
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3
--credential-type one of None, PSK, Password
--credential WLAN Password or PSK

Examples

To start an AP

    $ffx wlan ap start

        --ssid TestNetwork

        --security-type wpa2

        --credential-type password

        --credential "Your very secure password here"

Notes

  • Only one application at a time can interact with the WLAN policy layer.

status

Provides the first available AP status update


Usage:  ffx wlan ap status
Options  
--help display usage information

Examples

To query current AP status

    $ ffx wlan ap status

stop

Stop an access point interface


Usage:  ffx wlan ap stop [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
Options  
--help display usage information
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3
--credential-type one of None, PSK, Password
--credential WLAN Password or PSK

Examples

To stop an AP

    $ffx wlan ap stop

        --ssid TestNetwork

        --security-type wpa2

        --credential-type password

        --credential "Your very secure password here"

Notes

  • Only one application at a time can interact with the WLAN policy layer.

stop-all

Stops all active APs


Usage:  ffx wlan ap stop-all
Options  
--help display usage information

Examples

To stop all APs

    $ ffx wlan ap stop-all

Notes

  • Only one application at a time can interact with the WLAN policy layer.

client

Controls WLAN client policy API.


Usage:  ffx wlan client [subcommand...]
Options  
--help display usage information
Subcommands  
batch-config Allows WLAN credentials to be extracted and restored.
connect Connect to the specified WLAN network
list-saved-networks Lists all networks saved by the WLAN policy layer.
listen Listens for policy client connections updates
remove-network WLAN policy network storage container
save-network WLAN policy network storage container
scan Scan for nearby WLAN networks.
start Allows wlancfg to automate WLAN client operation
status Provides the first available client status update
stop Stops automated WLAN policy control of client interfaces and

batch-config

Allows WLAN credentials to be extracted and restored.


Usage:  ffx wlan client batch-config [subcommand...]
Options  
--help display usage information
Subcommands  
dump Extracts a structured representation of the device's saved WLAN credentials.
restore Injects a structure representation of WLAN credentials into a device.
dump

Extracts a structured representation of the device's saved WLAN credentials.


Usage:  ffx wlan client batch-config dump
Options  
--help display usage information

Examples

To dump WLAN client configs

    $ ffx wlan client batch-config dump

Notes

  • Only one application at a time can interact with the WLAN policy layer.
restore

Injects a structure representation of WLAN credentials into a device.


Usage:  ffx wlan client batch-config restore serialized_config
Options  
--help display usage information

Examples

To restore WLAN client configs

    $ ffx wlan client batch-config restore

Notes

  • Only one application at a time can interact with the WLAN policy layer.

connect

Connect to the specified WLAN network


Usage:  ffx wlan client connect [--ssid <ssid>] [--security-type <security-type>]
Options  
--help display usage information
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3

Examples

To remove a WLAN network

    $ffx wlan client connect

        --ssid TestNetwork

        --security-type wpa2

Notes

  • Only one application at a time can interact with the WLAN policy layer.

list-saved-networks

Lists all networks saved by the WLAN policy layer.


Usage:  ffx wlan client list-saved-networks
Options  
--help display usage information

Examples

To list saved networks

    $ ffx wlan client list-saved-networks

Notes

  • Only one application at a time can interact with the WLAN policy
layer.

listen

Listens for policy client connections updates


Usage:  ffx wlan client listen
Options  
--help display usage information

Examples

To begin listening for client events

    $ ffx wlan client listen

remove-network

WLAN policy network storage container


Usage:  ffx wlan client remove-network [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
Options  
--help display usage information
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3
--credential-type one of None, PSK, Password
--credential WLAN Password or PSK

Examples

To remove a WLAN network

    $ffx wlan client remove-network

        --ssid TestNetwork

        --security-type wpa2

        --credential-type password

        --credential "Your very secure password here"

Notes

  • Only one application at a time can interact with the WLAN policy layer.

save-network

WLAN policy network storage container


Usage:  ffx wlan client save-network [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
Options  
--help display usage information
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3
--credential-type one of None, PSK, Password
--credential WLAN Password or PSK

Examples

To save a WLAN network

    $ffx wlan client save-network

        --ssid TestNetwork

        --security-type wpa2

        --credential-type password

        --credential "Your very secure password here"

Notes

  • Only one application at a time can interact with the WLAN policy layer.

scan

Scan for nearby WLAN networks.


Usage:  ffx wlan client scan
Options  
--help display usage information

Examples

To scan

    $ ffx wlan client scan

Notes

  • Only one application at a time can interact with the WLAN policy
layer.

start

Allows wlancfg to automate WLAN client operation


Usage:  ffx wlan client start
Options  
--help display usage information

Examples

To start client connections

    $ ffx wlan client start

Notes

  • Only one application at a time can interact with the WLAN policy
layer.

status

Provides the first available client status update


Usage:  ffx wlan client status
Options  
--help display usage information

Examples

To query client status

    $ ffx wlan client status

stop

Stops automated WLAN policy control of client interfaces and destroys all client interfaces.


Usage:  ffx wlan client stop
Options  
--help display usage information

Examples

To stop client connections

    $ ffx wlan client stop

Notes

  • Only one application at a time can interact with the WLAN policy
layer.

deprecated

Controls to-be-deleted WLAN functionality.


Usage:  ffx wlan deprecated [subcommand...]
Options  
--help display usage information
Subcommands  
suggest-mac Notifies WLAN policy of a MAC address that ought to be used when creating new AP interfaces

suggest-mac

Notifies WLAN policy of a MAC address that ought to be used when creating new AP interfaces


Usage:  ffx wlan deprecated suggest-mac mac
Options  
--help display usage information

Examples

To suggest an AP MAC address

    $ ffx wlan deprecated suggest-mac 01:02:03:04:05:06