Bn

bn

Use the live GUI database through bn. Start with bn target list; use bn doctor if bridge state is unclear. With multiple views open, pass the returned --target <selector> or set BN_TARGET. Omission works only with one view. --target active deliberately follows the GUI tab.

Read only what the task needs

bn function search player
bn function info player_update
bn decompile player_update
bn disasm player_update
bn disasm 0x401234 --count 20
bn disasm 0x401234 --end 0x401280
bn xrefs player_update
bn refs player_update
bn bundle function player_update projectile_update --include decompile,disasm --out /tmp/functions.json

function info is a compact summary; add --locals or use local list for full variable details. Bundles default to decompile, disassembly, and outbound references. --include all exports every section without duplicating HLIL. Multiple-function bundles retain successful reads alongside per-function errors and exit nonzero if any fail.

Linear disasm --count/--end works without a containing function and reports where decoding stops. --end is exclusive. For windows in an analyzed function use --before-instructions/--after-instructions. With --match, --before/--after always count text lines; without --match, disassembly also accepts them as legacy instruction-window aliases.

Use bn schema disasm or bn schema function info for scoped argument discovery. --help works on each command. Whole-database search text and search constant have a five-second default analysis budget; function search does not take --timeout.

Output

• JSON and NDJSON stream complete results by default. Use --spill explicitly to receive an artifact envelope for large results.
• Text over 40,000 bytes spills to a unique file, with a short preview on stdout and metadata on stderr. Use --no-spill for text pipelines.
• --out <path> writes the full result and returns an artifact envelope with size and hash.
• --match <regex> filters text before spill accounting. --before/--after supply matching-line context.
• Optional --tokens adds artifact token counts if the bn-cli[tokens] extra and tokenizer are available. Normal output needs neither.

Python is a first-class analysis path

Use BN directly for custom analysis. bn py exec remains an alias. Pipe multiline code with a quoted heredoc:

bn py <<'PY'
f = function("player_update")
result = {"address": hex(f.start), "hlil_count": sum(1 for _ in f.hlil.instructions)}
PY

Use --code for one-liners or --script for saved scripts. Shell quoting is not JSON quoting; do not pass multiline code through JSON.stringify as shell escaping. Inputs are syntax-checked before contacting BN.

The scope includes unrestricted bn/binaryninja, bv/current_view, address, function, functions_containing, typed read_u*/read_i*, read_ptr, read_f32, read_f64, read_cstr, and result. BN iterators may need explicit materialization. Stdout and result are returned; non-JSON results use repr with a warning. Python writes are unrestricted and do not inherit the built-in mutation transaction guarantees.

Types and mutations

Use types show/struct show as authoritative layouts when decompile presentation is stale. For edits, prefer the built-in preview and verification path:

bn proto set player_update "void player_update(Player* self)" --preview
bn struct field set Player 0x308 movement_flag_selector uint32_t --preview

Preview applies, verifies, and reverts. Non-preview writes verify the live post-state and revert on failure. Inspect results, affected_functions, and affected_types; use local_id from local list for local edits. Read back relevant types/prototypes and decompile after changes. bn refresh can refresh stale analysis presentation. User-requested raw Python writes still require appropriate readback.

For exact native call/return addresses, use callsites rather than inferring from HLIL. Read references/callsites.md for caller-static mapping and scoped recovery.