CLI Reference

A command-line interface for managing Stash from your terminal — push history events and manage all resources.

Install

pip install stashai

First-time setup

Run the interactive setup wizard. It configures the API endpoint, authenticates you (login or register), and creates a workspace — all in one shot. No manual config editing required.

stash connect

The wizard saves everything to ~/.stash/config.json. Once complete, commands like stash history push work without extra flags.

Auth commands

stash login <name> --password <pw>       # Password login
stash signin                            # Sign in through the browser
stash register <name>                   # Create a new account
stash auth <url> --api-key <key>        # Store existing credentials
stash whoami                            # Show the current logged-in user
stash disconnect                        # Sign out and clear config
stash config [key] [value]              # View or update any config value

After stash connect, your defaults are stored. You can still override any value: e.g. stash config base_url https://joinstash.ai or set STASH_API_KEY / STASH_URL as environment variables for CI and scripts.

Notebooks

stash notebooks list [--ws ID] [--all]
stash notebooks create <name> [--ws ID] [--personal]
stash notebooks pages <notebook_id> [--ws ID]
stash notebooks add-page <nb_id> <name> [--content "..."]
stash notebooks read-page <nb_id> <page_id>
stash notebooks edit-page <nb_id> <page_id> --content "..."

History

stash history push <content> [--ws ID] [--agent cli] [--type message]
stash history query [--ws ID] [--agent X] [--type Y] [-n 50] [--all]
stash history search <query> [--ws ID] [-n 50]
stash history agents [--ws ID]
stash history transcript <session_id> [--ws ID]

Tables

stash tables list [--ws ID] [--all] [--personal]
stash tables create <name> [--ws ID] [--columns JSON]
stash tables rows <table_id> [--sort COL] [--filter COL]
stash tables insert <table_id> <data_json>
stash tables import <table_id> <file> [--format csv|json]
stash tables export <table_id>
stash tables count <table_id>
stash tables update-row <table_id> <row_id> <data_json>
stash tables delete-row <table_id> <row_id>

Files

stash files upload <path> [--ws ID]
stash files list [--ws ID]
stash files rm <file_id>
stash files text <file_id>

Streaming & hooks

Install Stash hooks for all supported coding agents on your $PATH, then enable or disable streaming per repo:

stash install                           # Install hook plugins
stash enable                            # Enable streaming for this repo
stash disable                           # Disable streaming for this repo
stash settings                          # Interactive settings page