piker command-line guide
========================

Piker installs three human-facing entry points with different jobs:

* ``piker`` is the main command group for broker, data, storage and UI tasks.
* ``pikerd`` is the long-running root service supervisor.  Clients such as
  ``chart`` connect to it, or start a service tree when none is running.
* ``ledger`` is the separate trade-ledger and position-accounting tool.  Its
  commands can contact brokers or update account data; it is not read-only.

See the `project README <../../README.rst>`_ for installation and runtime context.

Safe discovery and first run
----------------------------

From a checkout, these enter no broker, UI or account command body::

    uv run piker --help
    uv run piker chart --help
    uv run pikerd --help
    uv run ledger --help

Explicit ``--help`` prints usage and exits 0.  Repeat it at each command level.

A low-risk first runtime starts only the supervisor; stop it with ``Ctrl-C``::

    uv run pikerd -l info

It waits for client requests before starting broker or feed work.  Run this
intentionally long-lived process in its own terminal.

Root options come first
-----------------------

Click options precede the subcommand that consumes them.  ``--brokers``,
``--loglevel``, ``--configdir`` and ``--pdb`` are ``piker`` root options::

    uv run piker -l info -c /tmp/piker-profile chart <fqme>

Create the configuration directory first.  Do not move ``-l`` or ``-c`` after
``chart``; use ``piker chart --help`` for options owned by that subcommand.

For isolation, set ``XDG_CONFIG_HOME`` before any Piker process.  ``piker -c``
can also select an existing directory for that ``piker`` invocation::

    export XDG_CONFIG_HOME=/tmp/piker-xdg
    mkdir -p "$XDG_CONFIG_HOME/piker"
    uv run piker -c "$XDG_CONFIG_HOME/piker" --help

Output contracts
----------------

Parser errors are non-zero, but operational callbacks do not yet share one
failure-code contract.  Tables, colors, help prose and logs are human output.
Consume JSON only when that command advertises ``--json`` and pin automation to
its tested schema.  No CLI-wide JSON or stdout/stderr stability is promised.

Intentionally not guaranteed
----------------------------

Registry/service-list details, multiaddr syntax/routing, and storage commands,
SHM identities and disk layouts are volatile and intentionally not guaranteed.
Consult the running checkout; focused storage UX expectations live in
`tests/test_store_cli.py <../../tests/test_store_cli.py>`_.
