usage.txt

Usage: {progname} command [args...]

Configuration files are stored in $BOXTOOLS_DIR, by default ~/.boxtools

To maintain multiple user identities while using the same aliases, history,
etc., set $BOXTOOLS_AUTH_NAME to a non-blank value (this will affect only the
filename in which we keep our auth tokens).

Whenever a command expects a Box Item ID, you can use a special syntax
to lookup an ID encountered in recent ls or search commands:

  =name    Do an exact match on item names
  %name    Do a substring search on item names
  ^name    Do a prefix search on item names
  name$    Do a suffix search on item names and IDs
  /re/     use the ID of the item whose name or ID is matched by the
           case-insensitive regular expression re
  s/n      The double-focus operator! It's the best. Matches an item if
           the name includes s as a substring, and the ID ends with n.
  s;n      Like s/n but matches s case-insensitively (it's also the best).
  /p/s     Matches an item if the name includes s as a substring,
           and the parent folder name includes p.

For the =, %, ^, and $ operators, the sigil character can appear either
at the beginning or the end of the name.

If the ID is composed of 1-4 numeric digits, then it will be treated as the
n-th item printed by the last 'ls' or 'search' command. You can specify an
end-inclusive range of such items using the syntax 'n-m'. If a number has 5+
digits, it's treated as a literal numeric ID.

Finally, it's matched against known item names case-insensitively.

By appending a '!' to any of the above search terms, you can skip any
prompts to select among matching items, and automatically use the most
recently encountered matching item.

The one-character id '@' refers to the most recent ID successfully used
in the previous command (i.e. "ls 1234 @" won't list folder 1234 twice).
In the above example, the ID referred to by '@' is not changed to 1234;
however, if the command were "ls @ 1234" then '@' would become 1234.

The root folder, aka "All Files", has an ID of '0' or '/'.

The most recently listed (via 'ls') folder has an ID of '.' and its
parent is '..'.

== Aliases ==

  Aliases may be defined via an '@alias = ID [# comment]' command. If a
  typed ID begins with '@', the rest of the ID word will be checked
  against these aliases. '@list' will list all defined aliases.
  '@list term' will list only those aliases that contain 'term'; if
  'term' begins with a '^' it anchors the search to the start of the
  alias name. To delete an alias, use '@alias = None' or '@alias = ""'.

  Aliases that begin with '_' or whose names are only one letter or all
  digits will not be persisted to the next session. Aliases will be
  saved to the "id-aliases.txt" file in your config directory; this file
  may be manually edited.

  You can sort your aliases by using the '@sort' command. If the first
  argument is 'c' or 'comment', aliases will be sorted by the comment
  (case-folded); otherwise, they'll be sorted by alias name.

When using the 'shell' command, any input line that starts with '!' will
be passed to the system shell after stripping off the '!'.

The 'tree' command has flags for adding encountered files and folders to
the "item stash". The items in the stash may then be referred to by the
ID '@@' in relevant commands (those that accept multiple non-trash IDs).
The 'stash' command lets you manipulate and display the list of stashed
items. You can also display the contents of the stash by using '@@' as
a command.

------------------------------------------------------------------------
  BOXTOOLS_APP_DIR = {app_dir}
  BOXTOOLS_DIR     = {config_dir}
------------------------------------------------------------------------

Commands:
    auth          Obtain auth tokens via OAuth2
    refresh       Refresh existing auth tokens
    token         Print access token to stdout

    userinfo      Print authorized user info
    history,hist  Show previous ID history

    ls, list      List contents of a folder
    fd, search    Search for items
    tree          Display a tree of items and add to stash

    get           Download files or representations
    zip           Download a ZIP file of items
    repr          Get represenation information
    put           Upload files
    cat           Write the contents of files or web-links to stdout
    mkdir         Create a new folder
    rm, del       Remove files or folders
    mv, move      Move files or folders
    cp, copy      Copy files or folders
    rn, rename    Rename a file or folder

    ln, link      Get links for files or folders
    readlink      Get the item referred to by a shared link
    path          Get full path of files or folders
    stat          Get info about the item referred to by a shared link
    desc          Print or update the description of a file or folder
    trash         List, view, restore, or purge items in the trash.
    ver, version  List, download, and manipulate file versions
    unspace       Rename items to remove spaces and other odd chars
    stash         Manipulate the item stash

    source        Read commands from a given file
    shell         Enter an interactive shell. Certain commands are handled
                  internally by the shell:

                    q(uit)/e(xit)     exit the shell
                    h(elp)/?          general usage
                    cd [dir]          change directory
                    pwd               print current directory


Use "{progname} [command] --help" for more information about a command.