afni [options] [session_directory ...]

   -bysub       This new [01 Feb 2018] option allows you to have 'sessions'
                  made up from files scattered across multiple directories.
                  The purpose of this option is to gather all the datasets
                  corresponding to a single subject identifier, as is done
                  in the BIDS file hierarchy -- [bids.neuroimaging.io]
               ** After '-bysub' you put one or more subject identifiers,
                  which are of the form 'sub-XXX' where 'XXX' is some
                  subject code (it does not have to be exactly 3 characters).
               ** If an identifier does NOT start with 'sub-', then that
                  4 letter string will be added to the front. This allows
                  you to specify your subjects by their numbers 'XXX' alone.
               ** The list of subject identifiers ends when an argument
                  on the command line starts with the '-' character.
                  That would be another option, or the '-' character
                  by itself if the next things on the command line
                  are the list of directories to scan for datasets.
               ** Each directory on the command line (after all options)
                  will be scanned recursively (down the file tree) for
                  subdirectories whose name matches the 'sub-XXX' identifier
                  exactly. All such subdirectories will have all their
                  datasets read in (recursively down the file tree) and
                  put into a single session for viewing in AFNI.
               ** Remember: if no directories are given on the command
                  line after the various options, then the current working
                  directory ('.' or 'echo $cwd') is used.
               ** If a directory on the command line does NOT have any
                  subdirectories that match any of the '-bysub' identifiers,
                  then that directory will be read in the normal way, with
                  all the datasets in that particular directory (but not
                  subdirectories) read into the session.
               ** Please note that '-bysub' sessions will NOT be rescanned
                  for new datasets that might get placed there after the
                  AFNI GUI starts, unlike normal (single directory) sessions.
               ** Example:
                    afni -bysub 10506 50073 - ~/data/OpenFMRI/ds000030
                  This will open the data for subjects 10506 and 50073 from
                  the data at the specified directory -- presumably the
                  data downloaded from [openfmri.org]
               ** If directory sub-10506 is found and has (say) sub-directories
                    anat beh dwi func
                  all AFNI-readable datasets from these sub-directories will
                  be input and collected into one session, to be easily
                  viewed together. In addition, if a sub-directory named
                    derivatives/sub-10506
                  is found underneath ~/data/OpenFMRI/ds000030, all the
                  datasets found underneath that will also be put into the
                  same session, so they can be viewed with the 'raw' data.
               ** In this context, 'dataset' also means .png and .jpg files
                  found in the sub-XXX directories. These images can be
                  opened in the AFNI GUI using the Axial image viewer.
                  (You might want to turn the AFNI crosshairs off!)
               ** If you do NOT want .png and .jpg files read into AFNI,
                  set UNIX environment variable AFNI_IMAGE_DATASETS to 'NO'.
               ** You can put multiple subject IDs after '-bysub', as
                  in the example above. You can also use the '-bysub' option
                  more than once, if you like. Each distinct subect ID will
                  get a distinct AFNI session.