/ 
App-FileSync-0.001.1
/ App::FileSync::CLI

NAME

App::FileSync::CLI - the filesync, filesync-admin and filesync-server commands

SYNOPSIS

# bin/filesync
use App::FileSync::CLI;
exit App::FileSync::CLI::run_client(@ARGV);

DESCRIPTION

Each run_* function runs one command line and returns the exit code; it never dies. Errors are reported through the logger (or standard error if the settings that configure the logger are themselves broken), without Perl file and line numbers. Text output goes to standard output; --json prints one JSON document instead.

Client exit codes: 0 ok, 1 fatal, 2 another run holds the lock, 3 completed with warnings, 4 verification found drift. Admin: 0, 1 and 4.

FUNCTIONS

run_client

Documented with "run_server" below.

run_admin

Documented with "run_server" below.

run_server

Purpose: run filesync, filesync-admin or filesync-server.

Args: the command line, without the program name.

Returns: the exit code.

Side Effects: whatever the command does; prints to standard output and logs to standard error. run_server speaks the protocol on standard input and output and refuses to run on a terminal unless FILESYNC_ALLOW_TTY is set.

Usage:

exit App::FileSync::CLI::run_client(@ARGV);

EXAMPLE

my $code = App::FileSync::CLI::run_client('sync', '--repo', 'docs', '--json');
my $code = App::FileSync::CLI::run_admin('--root', '/srv/filesync', 'repo', 'list');

API SPECIFICATION

INPUT

[ { name => 'args', type => 'arrayref' } ]	# passed as a list

OUTPUT

{ type => 'integer', min => 0, max => 255 }

MESSAGES

Key                 Meaning                                   Resolution
cli.unknown_command the command is not known                  run "filesync help"
cli.usage.*         the options could not be parsed           see the usage line
cli.unexpected      extra arguments were given                remove them
cli.required        a required argument is missing            supply it
cli.no_repos        no repos are configured                   filesync init
cli.no_repo         the named repo is not configured          check --repo
cli.need_repo       several repos and no --repo               pass --repo
cli.init.*          init was given an unusable value          see the message
cli.server.*        the server was started wrongly            fix authorized_keys

FORMAL SPECIFICATION

run(args) = dispatch(args)                  if dispatch succeeds
run(args) = 1 ∧ log(strip_location(error))  if it raises

LIMITATIONS

  • Option parsing is Getopt::Long's: its own diagnostics for an unknown option are printed in English before the catalogued usage line.

  • --json output is not localised (field names and values such as never are data), while the text output is.

  • filesync-admin reads --root only before the command name.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

Usage is subject to the GPL2 licence terms. If you use it, please let me know.