| name | bn |
| description | Inspect and edit an already-open Binary Ninja database through the local bn CLI, including decompilation, disassembly, callsites, types, verified mutations, and unrestricted in-process Python. |
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.
