# SPDX-FileCopyrightText: 2021 RizinOrg <info@rizin.re>
# SPDX-License-Identifier: LGPL-3.0-only
#
#
# Format of RzCmdDesc/RzCmdDescHelp descriptor
# name: name of the YAML file, might be useful to reference another sub-file
# commands:
# - name: same as RzCmdDesc.name (mandatory)
#   cname: >
#     name used in the generated C code for structures, handlers, etc. Make sure
#     this is a valid C name. It cannot contain special characters like `$`, `"`,
#     `=`, etc.
#   summary: same as RzCmdDescHelp.summary (mandatory)
#   description: same as RzCmdDescHelp.description
#   type: >
#     same as RzCmdDescType. GROUP and ARGV_MODES are automatically detected
#     based on the other fields, the rest must be specified. ARGV is the default
#     mode if not specified.
#   args_str: same as RzCmdDescHelp.args_str
#   usage: same as RzCmdDescHelp.usage
#   options: same as RzCmdDescHelp.options
#   modes: >
#     same as RzCmdDesc.modes. When present the type is automatically set to
#     ARGV_MODES.
#   default_mode: >
#     same as RzCmdDesc.default_mode.
#   details: >
#     an array of RzCmdDescDetail or a string referencing an already existing
#     RzCmdDescDetail array
#   args: >
#     an array of RzCmdDescArg or a string referencing an already existing
#     RzCmdDescArg array
#   handler: >
#     name of the C handler that handles the command. If not specified it is based
#     on the cname.
#   subcommands: >
#     array of RzCmdDesc/RzCmdDescHelp descriptors. When present the
#     type is RZ_CMD_DESC_TYPE_GROUP. Only the first subcommand can contain a
#     descriptor with the same name as this one.
#
# Format of RzCmdDescDetail:
#   details:
#     - name: same as RzCmdDescDetail.name (mandatory)
#       entries: array of RzCmdDescDetailEntry (mandatory)
#
# Format of RzCmdDescDetailEntry:
#   entries:
#     - text: same as RzCmdDescDetailEntry.text (mandatory)
#       comment: same as RzCmdDescDetailEntry.comment (mandatory)
#       arg_str: same as RzCmdDescDetailEntry.arg_str
#
# Format of RzCmdDescArg:
#   args:
#     - name: same as RzCmdDescArg.name (mandatory)
#       optional: same as RzCmdDescArg.optional
#       no_space: same as RzCmdDescArg.no_space
#       type: same as RzCmdDescArg.type (mandatory)
#       flags: same as RzCmdDescArg.flags
#       default_value: same as RzCmdDescArg.default_value
#       choices: same as RzCmdDescArg.choices (only valid if type is RZ_CMD_ARG_TYPE_CHOICES)
#       choices_cb: same as RzCmdDescArg.choices_cb (only valid if type is RZ_CMD_ARG_TYPE_CHOICES)
#
---
name: root
commands:
  - name: "!"
    summary: Run command via system(3)
    subcommands: cmd_system
  - name: _
    cname: last_output
    summary: Print last output
    args: []
  - name: "#!"
    cname: hash_bang
    summary: Run interpreter
    args:
      - name: interpreter-name
        type: RZ_CMD_ARG_TYPE_STRING
        no_space: true
      - name: arg
        type: RZ_CMD_ARG_TYPE_STRING
        flags: RZ_CMD_ARG_FLAG_ARRAY
        optional: true
    details:
      - name: Examples
        entries:
          - text: "#!"
            arg_str: "python"
            comment: Run python commandline
          - text: "#!"
            arg_str: "python foo.py"
            comment: Run foo.py python script
          - text: "#!"
            arg_str: "python foo.py arg1"
            comment: Run foo.py python script and pass it arg1 as argument
    details_cb: rz_hash_bang_details_cb
  - name: $
    summary: Alias commands and strings
    subcommands: cmd_alias
  - name: "&"
    summary: Manage tasks
    subcommands: cmd_tasks
  - name: "("
    summary: Manage scripting macros
    subcommands: cmd_macro
    details:
      - name: Examples
        entries:
          - text: (
            arg_str: ""
            comment: List defined macros
          - text: (
            arg_str: foo; echo Disassemble 10 bytes at 0x10000; pd 10 @ 0x10000)
            comment: Define a new macro 'foo', which executes `?` followed by `pd` when called.
          - text: (
            arg_str: foo a b; echo Disassemble ${a} bytes at ${b}; pd ${a} @ ${b})
            comment: Define a new macro 'foo' with two arguments. ${a}/${b} are replaced before execution.
          - text: (-
            arg_str: foo
            comment: Remove previously defined macro named 'foo'
  - name: "*"
    cname: pointer
    summary: Pointer read/write data/values
    description: >
      Read or write values at a given address. When the value is a hexstring,
      it is decoded and written as raw bytes. Otherwise, it is evaluated as an
      expression and written using the current endianness and bitness settings.
    args_str: "<addr>[=<expr>|<hexstring>]"
    args:
      - name: addr
        type: RZ_CMD_ARG_TYPE_RZNUM
      - name: value
        type: RZ_CMD_ARG_TYPE_RZNUM
        optional: true
    details:
      - name: Examples
        entries:
          - text: "*"
            arg_str: "entry0=cc"
            comment: write trap in entrypoint
          - text: "*"
            arg_str: "entry0+10=0x804800"
            comment: write 0x804800 with the current bitness, 10 bytes from the entrypoint
          - text: "*"
            arg_str: "$$=[entry0] @e:asm.bits=32"
            comment: write the 32-bits value read at the entrypoint to the current offset
          - text: "*"
            arg_str: "entry0"
            comment: read the value contained at the entrypoint
  - name: "."
    summary: Interpret commands
    subcommands: cmd_interpret
  - name: "/"
    summary: Search for bytes, regexps, patterns, ..
    subcommands: cmd_search
  - name: "R"
    summary: Connect with other instances of rizin
    subcommands: cmd_remote
  - name: "?*"
    summary: Search help commands
    type: RZ_CMD_DESC_TYPE_GROUP
    subcommands: cmd_help
  - name: "%"
    cname: cmd_math
    summary: Math commands
    type: RZ_CMD_DESC_TYPE_GROUP
    subcommands: cmd_math
  - name: <
    cname: push_escaped
    summary: Push escaped string into the RzCons.readChar (pressed keys) buffer
    args:
      - name: characters
        type: RZ_CMD_ARG_TYPE_STRING
    details:
      - name: "Examples"
        entries:
          - text: "< ppq; <command>"
            comment: "Equivalent to running <command> and pressing the keys: p, p, q."
          - text: "< \\n; <command>"
            comment: "As above, but '\\n' is equivalent to pressing <enter>."
      - name: "Escape sequences"
        entries:
          - text: "\\n"
            comment: "newline (0x0a)."
          - text: "\\b"
            comment: "backspace (0x08)."
          - text: "\\t"
            comment: "horizontal tab (0x09)."
          - text: "\\v"
            comment: "vertical tab (0x0b)."
          - text: "\\f"
            comment: "new page (0x0c)."
          - text: "\\r"
            comment: "carriage return (0x0d)."
          - text: "\\xHH"
            comment: "Raw byte 0xHH (in hexadecimal)."
  - name: a
    cname: cmd_analysis
    summary: Analysis commands
    subcommands: cmd_analysis
  - name: b
    summary: Display or change the block size
    subcommands: cmd_block
  - name: B
    summary: Computes the possibles firmware locations in memory a.k.a basefind (CPU intensive)
    cname: basefind_compute
    type: RZ_CMD_DESC_TYPE_ARGV_STATE
    default_mode: RZ_OUTPUT_MODE_TABLE
    modes:
      - RZ_OUTPUT_MODE_TABLE
      - RZ_OUTPUT_MODE_JSON
      - RZ_OUTPUT_MODE_QUIET
    args:
      - name: pointer_bits
        type: RZ_CMD_ARG_TYPE_CHOICES
        optional: true
        choices: ["32", "64"]
    details:
      - name: "Settings of this command"
        entries:
          - text: "Check out the settings for this command with 'el basefind.'"
            comment: ""
  - name: c
    summary: Compare block with given data
    subcommands: cmd_cmp
  - name: C
    summary: Code metadata (comments, format, hints, ..)
    subcommands: cmd_meta
  - name: d
    summary: Debugger commands
    subcommands: cmd_debug
  - name: e
    summary: List/get/set config evaluable vars
    subcommands: cmd_eval
  - name: f
    summary: Manage flags
    subcommands: cmd_flag
  - name: m
    summary: Manage marks
    subcommands: cmd_mark
  - name: F
    summary: FLIRT signature management
    subcommands: cmd_flirt
  - name: g
    summary: Generate shellcodes with rz_egg
    subcommands: cmd_egg
  - name: help
    summary: Generic help
    cname: help
    args: []
  - name: H
    summary: Rizin history commands.
    subcommands: cmd_history
  - name: i
    summary: Get info about opened binary file
    subcommands: cmd_info
  - name: k
    summary: Run query (SDB)
    subcommands: cmd_query
  - name: L
    summary: List, unload, load rizin plugins
    subcommands: cmd_plugins
  - name: o
    summary: Open files and handle opened files
    subcommands: cmd_open
  - name: p
    cname: cmd_print
    summary: Print commands
    subcommands: cmd_print
  - name: P
    summary: Project management
    subcommands: cmd_project
  - name: q
    summary: Quit rizin
    subcommands: cmd_quit
  - name: r
    subcommands: cmd_resize
    summary: Resize file
  - name: s
    summary: Seek commands
    subcommands: cmd_seek
  - name: t
    summary: Types, noreturn, signatures, C parser and more
    subcommands: cmd_type
  - name: V
    summary: Interactive mode
    subcommands: cmd_interactive
  - name: v
    summary: Interactive panel mode
    subcommands: cmd_interactive_panel
  - name: w
    summary: Write commands
    subcommands: cmd_write
  - name: x
    summary: Alias for 'px' (print hexdump).
    cname: print_hexdump_alias
    type: RZ_CMD_DESC_TYPE_ARGV_STATE
    modes:
      - RZ_OUTPUT_MODE_STANDARD
      - RZ_OUTPUT_MODE_JSON
    args:
      - name: len
        type: RZ_CMD_ARG_TYPE_RZNUM
        optional: true
  - name: xc
    summary:  Alias for 'pxc' (show hexdump with comments).
    cname: print_hexdump_comments_alias
    args:
      - name: len
        type: RZ_CMD_ARG_TYPE_RZNUM
        optional: true
  - name: y
    summary: Yank/paste bytes from/to memory
    subcommands: cmd_yank
  - name: "@"
    cname: tmp_modifiers
    options: "[?]"
    summary: "'@' help, temporary modifiers, applied left-to-right"
    type: RZ_CMD_DESC_TYPE_FAKE
    usage: "<cmd> <@> <args> [<@> <args> ...]"
    details:
      - name: ""
        entries:
          - text: "<cmd> @ "
            arg_str: "<addr>"
            comment: "Temporary seek to <addr>"
          - text: "<cmd> @ "
            arg_str: "..<addr>"
            comment: "Temporary partial address seek (see s..)"
          - text: "<cmd> @!"
            arg_str: "<blocksize>"
            comment: "Temporary change the block size"
          - text: "<cmd> @("
            arg_str: "<from> <to>)"
            comment: "Temporary set from and to for commands supporting ranges"
          - text: "<cmd> @a:"
            arg_str: "<arch>[:<bits>]"
            comment: "Temporary set arch and bits, if specified"
          - text: "<cmd> @b:"
            arg_str: "<bits>"
            comment: "Temporary set asm.bits"
          - text: "<cmd> @B:"
            arg_str: "<nth>"
            comment: >
              Temporary seek to nth instruction in current basic block
              (negative numbers too)
          - text: "<cmd> @e:"
            arg_str: "<k>=<v>[,<k>=<v>]"
            comment: >
              Temporary change eval vars (multiple vars separated by comma)
          - text: "<cmd> @f:"
            arg_str: "<file>"
            comment: "Temporary replace block with file contents"
          - text: "<cmd> @F:"
            arg_str: "<flagspace>"
            comment: "Temporary change flag space"
          - text: "<cmd> @i:"
            arg_str: "<nth.op>"
            comment: "Temporary seek to the Nth relative instruction"
          - text: "<cmd> @k:"
            arg_str: "<key>"
            comment: "Temporary seek at value of sdb key `key`"
          - text: "<cmd> @o:"
            arg_str: "<fd>"
            comment: "Temporary switch to another fd"
          - text: "<cmd> @r:"
            arg_str: "<reg>"
            comment: "Temporary seek to register value"
          - text: "<cmd> @s:"
            arg_str: "<string>"
            comment: "Temporary replace block with string"
          - text: "<cmd> @v:"
            arg_str: "<value>"
            comment: "Temporary replace block with value, written according to asm.bits and cfg.bigendian"
          - text: "<cmd> @x:"
            arg_str: "<hexstring>"
            comment: "Temporary replace block with hexstring"
  - name: "@@"
    cname: iterators
    options: "[?]"
    summary: "'@@' help, iterators"
    type: RZ_CMD_DESC_TYPE_FAKE
    usage: "<cmd> <@@> <args>"
    details:
      - name: ""
        entries:
          - text: "<cmd> @@."
            arg_str: " <file>"
            comment: >
              Run <cmd> over the offsets specified in <file>, one per line
          - text: "<cmd> @@="
            arg_str: "<addr1> [<addr2> ...]"
            comment: "Run <cmd> over the listed addresses"
          - text: "<cmd> @@@="
            arg_str: "<addr1> <blksz1> [<addr2> <blksz2> ...]"
            comment: >
              Run <cmd> over the listed addresses and set the proper block size
          - text: "<cmd> @@/"
            arg_str: "<search-cmd>"
            comment: "Run <cmd> over the search results of /<search-cmd>"
          - text: "<cmd> @@c:"
            arg_str: "<cmd2>"
            comment: "Run <cmd> on all addresses in the output of <cmd2>"
          - text: "<cmd> @@@c:"
            arg_str: "<cmd2>"
            comment:
              Run <cmd> on all addresses/blocksizes in the output of <cmd2>,
              similar to @@@=
          - text: "<cmd> @@C"
            arg_str: "[:<glob>]"
            comment:
              Run <cmd> over all comments matching <glob>. <glob> may contain
              `*` to indicate multiple chars. If not specified all comments are
              considered.
          - text: "<cmd> @@dbt[abs]"
            arg_str: ""
            comment: "Run <cmd> on every backtrace address, bp or sp"
          - text: "<cmd> @@t"
            arg_str: ""
            comment: "Run <cmd> over all threads"
          - text: "<cmd> @@b"
            arg_str: ""
            comment: "Run <cmd> over all basic blocks of the current function"
          - text: "<cmd> @@i"
            arg_str: ""
            comment: "Run <cmd> over all instructions of the current basic block"
          - text: "<cmd> @@ii"
            arg_str: ""
            comment: "Run <cmd> over all imports"
          - text: "<cmd> @@iS"
            arg_str: ""
            comment: "Run <cmd> over all sections"
          - text: "<cmd> @@iSS"
            arg_str: ""
            comment: "Run <cmd> over all segments"
          - text: "<cmd> @@is"
            arg_str: ""
            comment: "Run <cmd> over all symbols"
          - text: "<cmd> @@iz"
            arg_str: ""
            comment: "Run <cmd> over all strings"
          - text: "<cmd> @@f"
            arg_str: "[:<glob>]"
            comment:
              Run <cmd> over all flags matching <glob>. <glob> may contain `*`
              to indicate multiple chars. If not specified all flags are
              considered.
          - text: "<cmd> @@F"
            arg_str: "[:<glob>]"
            comment:
              Run <cmd> over all functions matching <glob>. <glob> may contain
              `*` to indicate multiple chars. If not specified all functions
              are considered.
          - text: "<cmd> @@om"
            arg_str: ""
            comment: "Run <cmd> over all iomap (see `om`)"
          - text: "<cmd> @@dm"
            arg_str: ""
            comment: "Run <cmd> over all debug maps (see `dm`)"
          - text: "<cmd> @@r"
            arg_str: ""
            comment: "Run <cmd> over all registers"
          - text: "<cmd> @@s:"
            arg_str: "<from> <to> <step>"
            comment:
              Run <cmd> on all addresses starting from <from> and going up to
              <to> (excluded), with a step <step>.
  - name: ">"
    cname: redirection
    options: "[?]"
    summary: Redirection help ('>')
    type: RZ_CMD_DESC_TYPE_FAKE
    usage: "<cmd> > <arg>"
    details:
      - name: ""
        entries:
          - text: "<cmd> >"
            arg_str: " <file>|<$alias>"
            comment:
              Redirect STDOUT of <cmd> to <file> or save it to an alias (see
              $?)
          - text: "<cmd> 2>"
            arg_str: " <file>|<$alias>"
            comment:
              Redirect STDERR of <cmd> to <file> or save it to an alias (see
              $?)
          - text: "<cmd> H>"
            arg_str: " <file>|<$alias>"
            comment:
              Redirect HTML output of <cmd> to <file> or save it to an alias
              (see $?)
  - name: "|"
    cname: pipe
    options: "[?]"
    summary: Pipe help ('|')
    type: RZ_CMD_DESC_TYPE_FAKE
    usage: "<cmd> |[<program>|H|T|.|]"
    details:
      - name: ""
        entries:
          - text: "<cmd> |"
            comment: "Disable scr.html and scr.color"
          - text: "<cmd> |H"
            comment: "Enable scr.html, respect scr.color"
          - text: "<cmd> |"
            arg_str: " <program>"
            comment: "Pipe output of command to program"
          - text: "<cmd> |."
            comment: "Alias for .<cmd>"
  - name: "~"
    cname: grep
    options: "[?]"
    summary: Internal grep help ('~')
    type: RZ_CMD_DESC_TYPE_FAKE
    usage: "<command>~[modifier][word,word][endmodifier][[column]][:line]"
    details:
      - name: Modifiers
        entries:
          - text: "&"
            comment: "All words must match to grep the line"
          - text: "$[n]"
            comment: "Sort numerically / alphabetically the Nth column"
          - text: "$!"
            comment: "Sort in inverse order"
          - text: ","
            comment: "Token to define another keyword"
          - text: "+"
            comment: "Set the grep as the opposite of search.case_sensitive"
          - text: "^"
            comment: "Words must be placed at the beginning of line, after whitespace if any"
          - text: "<"
            comment: "Perform zoom operation on the buffer"
          - text: "!"
            comment: "Negate grep"
          - text: "?"
            comment: "Count number of matching lines"
          - text: "?."
            comment: "Count number chars"
          - text: ":s..e"
            comment: "Show lines s-e"
          - text: ".."
            comment: "Internal 'less'"
          - text: "..."
            comment: "Internal 'hud' (like V_)"
          - text: "{:"
            comment: "Human friendly indentation (yes, it's a smiley)"
          - text: "{:.."
            comment: "Less the output of {:"
          - text: "{:..."
            comment: "Hud the output of {:"
          - text: "{}"
            comment: "Json indentation"
          - text: "{}.."
            comment: "Less json indentation"
          - text: "{}..."
            comment: "Hud json indentation"
          - text: "{path}"
            comment: "Json path grep"
      - name: EndModifiers
        entries:
          - text: "$"
            comment: Words must be placed at the end of line
      - name: Columns
        entries:
          - text: "[n]"
            comment: Show only columns n
          - text: "[n-m]"
            comment: Show column n to m
          - text: "[n-]"
            comment: Show all columns starting from column n
          - text: "[i,j,k]"
            comment: Show the columns i, j and k
      - name: Examples
        entries:
          - text: i
            arg_str: "~:0"
            comment: Show first line of 'i' output
          - text: i
            arg_str: "~:-2.."
            comment: Show from the second-last line to the last line of 'i' output
          - text: i
            arg_str: "~:..3"
            comment: Show first three lines of 'i' output
          - text: i
            arg_str: "~:2..5"
            comment: Show three lines of 'i' output starting from 2nd line
          - text: pd
            arg_str: "~mov"
            comment: Disasm and grep for mov
          - text: pi
            arg_str: "~[0]"
            comment: Show only opcode
          - text: i
            arg_str: "~0x400$"
            comment: Show lines ending with 0x400
  - name: ":"
    cname: specifiers
    options: "[?]"
    summary: Command specifiers (table-output only for now)
    type: RZ_CMD_DESC_TYPE_FAKE
    usage: "<command>[:<table_spec>[:<table_spec>...]][:<output_spec>]"
    details:
      - name: Table format specifiers (<table_spec>)
        entries:
          - text: "<col>/sort/rev"
            comment: Sort table by column <col> in reverse order.
          - text: "<col>/sortlen/rev"
            comment: Sort table by column <col> length in reverse order.
          - text: "<col>/cols[/<col2>[/<col3>...]]"
            comment: Show only specified columns in the table.
          - text: "<col>"
            comment: Show only column <col> (it must not have the same name as an output format specifier).
          - text: "<col>/gt/<val>"
            comment: Grep rows where column <col> is greater than <val>.
          - text: "<col>/ge/<val>"
            comment: Grep rows where column <col> is greater than or equal to <val>.
          - text: "<col>/lt/<val>"
            comment: Grep rows where column <col> is less than <val>.
          - text: "<col>/le/<val>"
            comment: Grep rows where column <col> is less than or equal to <val>.
          - text: "<col>/eq/<val>"
            comment: Grep rows where column <col> is equal to <val>.
          - text: "<col>/ne/<val>"
            comment: Grep rows where column <col> is not equal to <val>.
          - text: "<col|*>/uniq"
            comment: Only get the first row where column <col> or all columns are unique.
          - text: "*/page/<n_page>/<page_size>"
            comment: Show <page_size> rows starting from the page number <n_page>.
          - text: "*/head/<n_rows>"
            comment: Show the first <n_rows> rows.
          - text: "*/tail/<n_rows>"
            comment: Show the last <n_rows> rows.
          - text: "<col>/str/<value>"
            comment: Grep rows where string <value> is a substring of column <col>.
          - text: "<col>/strlen/<value>"
            comment: Grep rows where the length of column <col> is <value>.
          - text: "<col>/minlen/<value>"
            comment: Grep rows where the length of column <col> is greater than <value>.
          - text: "<col>/maxlen/<value>"
            comment: Grep rows where the length of column <col> is less than <value>.
          - text: "<col>/sum/<value>"
            comment: Sum all the values of column <col>.
      - name: Output format specifiers (<output_spec>)
        entries:
          - text: csv
            comment: Print the table in CSV format.
          - text: json
            comment: Print the table in JSON format.
          - text: fancy
            comment: Print the table in a nice form with borders and headers.
          - text: simple
            comment: Print the table in a simple form, only with headers.
          - text: quiet
            comment: Print the table in a simple form, without headers.
      - name: Examples
        entries:
          - text: aflt
            arg_str: ":addr/cols/name/nbbs:nbbs/sort/dec:nbbs/gt/1:nbbs/lt/10:fancy"
            comment:
              Show only the address, name and number of basic blocks of the identified functions
              with more than 1 block but less than 10, sorted decrementally by number of blocks.
  - name: shell
    summary: Common shell commands
    sort_subcommands: true
    subcommands: cmd_shell
