To get an overview of available clans commands, run:
$ clans --help
To get help on a specific subcommand, like
$ clans edit --help
This will list all available arguments and option flags.
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 -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.
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
--logout is given, in which case the
authentication token will be deleted immediately after the command completes.
In addition, all commands accept
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.
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
$ 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.
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
$ 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:
editorvalue configured in the
- Failing that, the value of the
- Failing that,
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!
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.