Usage¶
To get an overview of available clans commands, run:
$ clans --help
To get help on a specific subcommand, like edit
, run:
$ clans edit --help
This will list all available arguments and option flags.
Logging in¶
All commands share several option flags related to authentication with the GrinnellPlans server:
-u USERNAME, --username USERNAME GrinnellPlans username, no brackets. -p PASSWORD, --password PASSWORD GrinnellPlans password. Omit for secure entry. --logout Log out before quitting.
By default, you must specify your username with -u
for every
clans
incantation:
$ clans -u <username> read <planname>
For example, to log in as user [baldwint], and read the [gorp] plan:
$ clans -u baldwint read gorp
This can be avoided by setting a default username in clans.cfg.
Clans stores active authentications like a browser does a cookie, so
it is not necessary to specify --password
each time.
In fact, it is a good idea to omit this flag as a rule.
If your password is required, you will be prompted for it.
Note
Clans remembers active authentications, but will only use them if
--username
is specified on the command line, or a default
username has been set in clans.cfg. This permits having multiple
concurrent Plans logins.
Authentications generally expire on the server side after two days of
inactivity, unless --logout
is given, in which case the
authentication token will be deleted immediately after the command completes.
In addition, all commands accept --help
and --version
options.
Reading Plans and Autoread Lists¶
To see what’s new on your autoread list:
$ clans list
This returns a list of plans on your autoread lists that have been updated since you last read them.
Note
Unfortunately clans does not currently know how to manage your autoread lists by adding/removing plans to it. This is coming in a future revision.
To read a plan, use the read
subcommand:
$ clans read <planname>
This displays the contents of the specified plan in a pager application in HTML format. It’s normally easier to read plain text, though:
$ clans read <planname> --format text
This formats the plan as plain text before displaying it.
Run clans read --help
for a list of available formatters. You can
configure a default formatter in clans.cfg.
Searching Plans and Quicklove¶
To search plans, use:
$ clans search <term>
This returns a lists of plans containing the search term, and a little
context. To restrict search to a planlove, use the --love
flag:
$ clans search --love <planname>
Searching for love of your own username (“quicklove”) gets a shortcut:
$ clans love
Editing Your Plan¶
To edit your own plan:
$ clans edit
This opens your plan for editing in a text editor. Clans decides which editor to use based on the following:
- The
editor
value configured in the[clans]
section ofclans.cfg
- Failing that, the value of the
$EDITOR
environment variable- Failing that,
pico
.
To submit your update, save and close the file. To cancel the update, quit from the editor without saving.
As an alternative to interactively editing your plan, you can use the
--from-file
option to use a text file as input:
$ clans edit --from-file <filename>
This replaces your entire plan with the contents of the specified text file. It will not prompt for confirmation, so use this option with caution!
Planwatch¶
To view a list of recently updated plans, use:
$ clans watch
By default, this displays a list of every plan updated in the last 12 hours. For a fresher list, you could do
$ clans watch 2
and only plans updated in the last 2 hours will be displayed.