<?xml version='1.0' encoding='utf-8'?>
<?xml-stylesheet href='style.xsl' type='text/xsl'?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' 'http://www.docbook.org/xml/4.5/docbookx.dtd'
[
	<!ENTITY p 'mbank-cli'>
	<!ENTITY version '20120216'>
	<!ENTITY select-accounts
'<para>
	You can select account(s) in the following ways:
	<itemizedlist>
		<listitem>
			<para>to select a single account — just provide its name;</para>
		</listitem>
		<listitem>
			<para>
				to select multiple accounts — use one of these options:
				<variablelist>
					<varlistentry>
						<term><option>-M</option></term>
						<term><option>--multiple-accounts</option></term>
						<listitem>
							<para>to select accounts specified in the command line,</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term><option>-A</option></term>
						<term><option>--all-accounts</option></term>
						<listitem>
							<para>
								to select all accounts.
							</para>
						</listitem>
					</varlistentry>
				</variablelist>
			</para>
		</listitem>
	</itemizedlist>
</para>'
	>
	<!ENTITY select-accounts-wildcard
'<para>
	You may use <userinput>*</userinput> as a wildcard character.
</para>'
>
	<!ENTITY output-format 'The output consists of lines in the following format:'>
	<!ENTITY tab-separated 'Fields are tab-separated.'>
	<!ENTITY omit-account-name '<replaceable>account-name</replaceable> will be omitted unless <option>M</option>/<option>--multiple-accounts</option> or <option>A</option>/<option>--all-accounts</option> option is used.'>
]>
<refentry>

<refentryinfo>
	<title>&p; manual</title>
	<productname>&p;</productname>
	<authorgroup>
		<author>
			<firstname>Jakub</firstname> <surname>Wilk</surname>
			<contrib>project leader</contrib>
			<email>jwilk@jwilk.net</email>
		</author>
		<author>
			<firstname>Łukasz</firstname> <surname>Indeka</surname>
			<contrib>developer</contrib>
			<email>lukaszindeka@o2.pl</email>
		</author>
		<author>
			<firstname>Piotr</firstname> <surname>Lewandowski</surname>
			<contrib>developer</contrib>
			<email>piotr.lewandowski@gmail.com</email>
		</author>
	</authorgroup>
</refentryinfo>

<refmeta>
	<refentrytitle>&p;</refentrytitle>
	<manvolnum>1</manvolnum>
	<refmiscinfo class='version'>&version;</refmiscinfo>
</refmeta>

<refnamediv>
	<refname>&p;</refname>
	<refpurpose>a command line interface to the on-line banking system of mBank</refpurpose>
</refnamediv>

<refsynopsisdiv>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='opt'>list</arg>
	</cmdsynopsis>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='plain'>history</arg>
		<group choice='opt'>
			<arg choice='plain'>
				<option>--range</option> <replaceable>start-date</replaceable> <replaceable>end-date</replaceable>
			</arg>
			<arg choice='plain'>
				<option>--from</option> <replaceable>start-date</replaceable>
				<arg choice='opt'><option>--to</option> <replaceable>end-date</replaceable></arg>
			</arg>
		</group>
		<group choice='req'>
			<arg choice='plain'><replaceable>account</replaceable></arg>
			<arg choice='plain'><option>-M</option> <arg choice='plain' rep='repeat'><replaceable>account</replaceable></arg></arg>
			<arg choice='plain'><option>-A</option></arg>
		</group>
	</cmdsynopsis>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='plain'>future</arg>
		<group choice='req'>
			<arg choice='plain'><replaceable>account</replaceable></arg>
			<arg choice='plain'><option>-M</option> <arg choice='plain' rep='repeat'><replaceable>account</replaceable></arg></arg>
			<arg choice='plain'><option>-A</option></arg>
		</group>
	</cmdsynopsis>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='plain'>withholdings</arg>
		<group choice='req'>
			<arg choice='plain'><replaceable>account</replaceable></arg>
			<arg choice='plain'><option>-M</option> <arg choice='plain' rep='repeat'><replaceable>account</replaceable></arg></arg>
			<arg choice='plain'><option>-A</option></arg>
		</group>
	</cmdsynopsis>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='plain'>funds</arg>
	</cmdsynopsis>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='plain'>deposits</arg>
	</cmdsynopsis>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='plain'>notices</arg>
	</cmdsynopsis>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='plain'>rename</arg>
		<group choice='plain'>
			<arg choice='plain'><replaceable>account</replaceable></arg>
		</group>
		<group choice='plain'>
			<arg choice='plain'><replaceable>new-name</replaceable></arg>
		</group>
	</cmdsynopsis>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='plain'>logout</arg>
	</cmdsynopsis>
	<cmdsynopsis>
		<command>&p;</command>
		<arg choice='opt' rep='repeat'><replaceable>option</replaceable></arg>
		<arg choice='plain'>void</arg>
	</cmdsynopsis>
</refsynopsisdiv>

<refsection>
	<title>Description</title>
	<para>
		<application>&p;</application> provides a rudimentary command line interface to the <ulink url="https://www.mbank.com.pl/">mBank online banking system</ulink>.
	</para>
</refsection>

<refsection>
	<title>Common options</title>
	<para>
		<command>&p;</command> accepts the following options, regardless the chosen action:
		<variablelist>
			<varlistentry>
				<term><option>--verbose</option></term>
				<listitem>
					<para>Display lots of debugging information.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>--debug</option> <replaceable>debug-directory</replaceable></term>
				<listitem>
					<para>
						Save debugging information (including dumps of downloaded pages)
						in the specified directory.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>--config</option> <replaceable>config-file</replaceable></term>
				<listitem>
					<para>Use <replaceable>config-file</replaceable> as an alternate configuration file.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>--cookie-jar</option> <replaceable>cookie-jar-file</replaceable></term>
				<listitem>
					<para>Use <replaceable>cookie-jar-file</replaceable> to store state of the phony web browser.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</para>
</refsection>

<refsection>
	<title>list action</title>
	<para>
		List available accounts.
	</para>
	<para>
		&output-format;
		<screen><replaceable>account-name</replaceable> <replaceable>account-no</replaceable> <replaceable>balance</replaceable> <replaceable>avail-resources</replaceable></screen>
		&tab-separated;
	</para>
</refsection>

<refsection>
	<title>history action</title>
	<para>
		Show the history of the selected account(s).
	</para>
	<para>
		Time range can be selected with the following options:
		<variablelist>
			<varlistentry>
				<term><option>--from</option> <replaceable>start-date</replaceable></term>
				<listitem>
					<para>Show operations with the date not before <replaceable>start-date</replaceable>.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>--range</option> <replaceable>start-date</replaceable> <replaceable>end-date</replaceable></term>
				<term><option>--from</option> <replaceable>start-date</replaceable> <option>--to</option> <replaceable>end-date</replaceable></term>
				<listitem>
					<para>
						Show operations with the date neither before <replaceable>start-date</replaceable>,
						nor after <replaceable>end-date</replaceable>.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
		Date can be ‘<literal>now</literal>’ or in the <literal><replaceable>YYYY</replaceable>-<replaceable>MM</replaceable>-<replaceable>DD</replaceable></literal> format.
	</para>
	&select-accounts;
	&select-accounts-wildcard;
	<para>
		&output-format;
		<screen><replaceable>account-name</replaceable> <replaceable>date</replaceable> <replaceable>accounting-date</replaceable> <replaceable>amount</replaceable> <replaceable>balance</replaceable> <replaceable>description</replaceable></screen>
		&tab-separated;
		&omit-account-name;
		<replaceable>description</replaceable> may consist of multiple lines, which are tab-separated in the output.
	</para>
</refsection>

<refsection>
	<title>future action</title>
	<para>
		Show list of planned operations for the selected account(s).
	</para>
	&select-accounts;
	&select-accounts-wildcard;
	<para>
		&output-format;
		<screen><replaceable>account-name</replaceable> <replaceable>date</replaceable> <replaceable>receiver</replaceable> <replaceable>title</replaceable> <replaceable>amount</replaceable> <replaceable>status</replaceable></screen>
		&tab-separated;
		&omit-account-name;
	</para>
</refsection>

<refsection>
	<title>withholdings action</title>
	<para>
		Show list of withholdings for the selected account(s).
	</para>
	&select-accounts;
	&select-accounts-wildcard;
	<para>
		&output-format;
		<screen><replaceable>account-name</replaceable> <replaceable>registration-date</replaceable> <replaceable>finalization-date</replaceable> <replaceable>amount</replaceable> <replaceable>title</replaceable></screen>
		&tab-separated;
		&omit-account-name;
	</para>
</refsection>

<refsection>
	<title>deposits action</title>
	<para>
		List time deposits.
	</para>
	<para>
		&output-format;
		<screen><replaceable>deposit-name</replaceable> <replaceable>establishment-date</replaceable> <replaceable>maturity-date</replaceable> <replaceable>term</replaceable> <replaceable>interest</replaceable> <replaceable>status</replaceable> <replaceable>amount</replaceable></screen>
		&tab-separated;
	</para>
</refsection>

<refsection>
	<title>funds action</title>
	<para>
		List available investment funds.
	</para>
	<para>
		&output-format;
		<screen><replaceable>fund-name</replaceable> <replaceable>amount</replaceable></screen>
		&tab-separated;
	</para>
</refsection>

<refsection>
	<title>notices action</title>
	<para>
		Show list of notices.
	</para>
	<para>
		&output-format;
		<screen><replaceable>new</replaceable> <replaceable>date</replaceable> <replaceable>title</replaceable></screen>
		&tab-separated;
		<replaceable>new</replaceable> can be either ‘<literal>N</literal>’ (for an unread notice) or ‘<literal></literal>’ (empty string — otherwise).
	</para>
</refsection>

<refsection>
	<title>rename action</title>
	<para>
		Change an account name.
	</para>
	&select-accounts-wildcard;
</refsection>

<refsection>
	<title>logout action</title>
	<para>
		Leave the web interace.
	</para>
</refsection>

<refsection>
	<title>void action</title>
	<para>
		Do (almost) nothing. Useful only for the debugging purposes.
	</para>
</refsection>

<refsection>
	<title>Usage examples</title>
	<screen><!--
--><prompt>$</prompt> <command>./&p;</command> list <lineannotation># list available accounts</lineannotation> &#10;
<prompt>$</prompt> <command>./&p;</command> history Foo <lineannotation># show history of the ‘Foo’ account</lineannotation> &#10;
<prompt>$</prompt> <command>./&p;</command> history Bar --range 2005-01-01 2005-12-31 &#10;
<prompt>$</prompt> <command>./&p;</command> history Quux --from 2006-06-01 &#10;
<prompt>$</prompt> <command>./&p;</command> future Foo <lineannotation># show list of planned operations for the ‘Foo’ account</lineannotation> &#10;
<prompt>$</prompt> <command>./&p;</command> rename 'eFoo - Bar' 'quux' <lineannotation># from now on, it will be called ‘eFoo - quux’</lineannotation> &#10;
<prompt>$</prompt> <command>./&p;</command> funds <lineannotation># list available investment funds</lineannotation> &#10;
<prompt>$</prompt> <command>./&p;</command> logout
	</screen>
</refsection>

<refsection>
	<title>Files</title>
	<para>(Due to experimental nature of <application>&p;</application>, these files are expected to be in same directory as the script itself.)</para>
	<variablelist>
		<varlistentry>
			<term><filename>mbank-cli.conf</filename></term>
			<listitem>
				<para>The default configuration file.</para>
				<para>You may specify an alternate configuration file with <option>--config</option> option.</para>
				<para>
					To create the configuration file, use the following command:
					<screen><!--
--><prompt>$</prompt> <command>umask</command> 077
<prompt>$</prompt> <command>cat</command> &lt;&lt;EOF | <command>gpg</command> --armor --encrypt --default-recipient-self &gt; <filename><replaceable>mbank-cli.conf</replaceable></filename>
<userinput>Login <replaceable>123456</replaceable>
Password "<replaceable>your-password</replaceable>"
EOF</userinput>
					</screen>
				</para>
				<para>
					Encrypting your configuration file with <command>gpg</command> is not necessary, but highly recommended.
				</para>
			</listitem>
		</varlistentry>
		<varlistentry>
			<term><filename>cookie-jar.txt</filename></term>
			<listitem>
				<para>State of the phony web browser.</para>
			</listitem>
		</varlistentry>
	</variablelist>
</refsection>

<refsection>
	<title>Exit codes</title>
	<para>
		The exit codes returned by <command>&p;</command> are as follows:
		<variablelist>
			<varlistentry>
				<term><errorcode>0</errorcode></term>
				<listitem>
					<para>Everything went fine.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><errorcode>1</errorcode></term>
				<listitem>
					<para>Failure because of an user error.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><errorcode>2</errorcode></term>
				<listitem>
					<para>
						Failure because of an <acronym>HTTP</acronym> error. This may be due to a network error but might as well be a result of an <acronym>API</acronym> error (see below).
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><errorcode>3</errorcode></term>
				<listitem>
					<para>
						Failure because of an unexpected behaviour of the web interface (so called ‘<literal>API error</literal>’).
						If you encounter this, please file a bug at <ulink url="http://code.google.com/p/mbank-cli/issues/list">the issue tracker</ulink>.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</para>
</refsection>

</refentry>

<!-- vim:set ts=4 sw=4 fenc=utf8: -->

