CLI Reference

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

Most commands accept --json for machine-readable output and --ws ID to target a specific workspace.

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.

Authentication

stash login<name> --password <pw>

Authenticate with username and password.

<name>stringREQUIRED

Your username.

--passwordstringREQUIRED

Your password.

stash signin[--api URL] [--no-browser] [--timeout N]

Open the browser for OAuth sign-in. Blocks until the user authorizes. Writes credentials on success and auto-selects the default workspace if there is exactly one.

--apistring

Stash API base URL. Override for self-hosted deployments. Defaults to https://api.stash.ac.

--pagestring

Sign-in page URL. Defaults to the /connect-token page matching --api.

--no-browserflag

Skip auto-opening the browser; just print the URL. Use on SSH or headless machines.

--timeoutnumber

Seconds to wait for sign-in. Defaults to 120.

stash register<name> [--password <pw>]

Create a new Stash account and store the API key.

<name>stringREQUIRED

Username for the new account.

--passwordstring

Password for the account.

stash auth<base_url> --api-key <key>

Store existing credentials for a Stash instance.

<base_url>stringREQUIRED

Base URL of the Stash server.

--api-keystringREQUIRED

Your API key.

stash whoami

Display the currently authenticated user.

stash disconnect

Sign out and clear all stored credentials so the next stash connect re-onboards.

stash config[key] [value] [--project]

View or update a configuration value. Keys: base_url, default_workspace, output_format. Run without arguments to show all config.

keystring

Config key to read or write.

valuestring

New value. Omit to read the current value.

--projectflag

Write to project-level config (.stash/config.json in the repo) instead of user config.

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.

Workspaces

stash workspaces list[--mine]

List workspaces you belong to.

--mineflag

Show only workspaces you own.

stash workspaces create<name> [--description TEXT] [--public]

Create a new workspace.

<name>stringREQUIRED

Name for the workspace.

--descriptionstring

Workspace description.

--publicflag

Make the workspace publicly visible.

stash workspaces join<invite_code>

Join a workspace by invite code.

<invite_code>stringREQUIRED

Invite code or magic link token.

stash workspaces use<workspace> [--scope user|project]

Set the default workspace for future commands. Accepts a workspace ID or name.

<workspace>stringREQUIRED

Workspace ID or name to set as default.

--scopestring

Where to write config: "user" or "project". Defaults to "user".

stash workspaces info<workspace_id>

Show workspace details.

<workspace_id>stringREQUIRED

ID of the workspace.

stash workspaces members<workspace_id>

List members of a workspace.

<workspace_id>stringREQUIRED

ID of the workspace.

Notebooks

stash notebooks list[--ws ID] [--all]

List notebooks in the current workspace.

--wsstring

Workspace ID override.

--allflag

Include notebooks from all workspaces.

stash notebooks create<name> [--ws ID] [--personal]

Create a new notebook collection.

<name>stringREQUIRED

Name for the notebook.

--wsstring

Workspace ID override.

--personalflag

Create as a personal notebook.

stash notebooks pages<notebook_id> [--ws ID]

List all pages in a notebook.

<notebook_id>stringREQUIRED

ID of the notebook.

--wsstring

Workspace ID override.

stash notebooks add-page<notebook_id> <name> [--content '...']

Add a new page to a notebook.

<notebook_id>stringREQUIRED

ID of the notebook.

<name>stringREQUIRED

Page title.

--contentstring

Initial page content.

stash notebooks read-page<notebook_id> <page_id>

Read the content of a notebook page.

<notebook_id>stringREQUIRED

ID of the notebook.

<page_id>stringREQUIRED

ID of the page.

stash notebooks edit-page<notebook_id> <page_id> --content '...'

Update the content of a notebook page. Reads from stdin if --content is not given.

<notebook_id>stringREQUIRED

ID of the notebook.

<page_id>stringREQUIRED

ID of the page.

--contentstring

New page content. Reads from stdin if omitted.

History

stash history push<content> [--agent cli] [--type message] [--session ID] [--attach FILE]

Push a new event to the workspace history stream.

<content>stringREQUIRED

Event content to push.

--wsstring

Workspace ID override.

--agentstring

Agent identifier. Defaults to "cli".

--typestring

Event type. Defaults to "message".

--sessionstring

Session ID to group events under.

--toolstring

Tool identifier.

--attachpath

Local file path to upload and attach. Repeatable.

--attach-idstring

Pre-uploaded file ID to attach. Repeatable.

stash history query[--agent X] [--type Y] [-n 50] [--all]

Query recent history events with optional filters.

--wsstring

Workspace ID override.

--agentstring

Filter by agent identifier.

--typestring

Filter by event type.

-n, --limitnumber

Maximum number of results. Defaults to 50.

--allflag

Query across all workspaces.

stash history search<query> [--ws ID] [-n 50]

Full-text search across workspace history.

<query>stringREQUIRED

Search query.

--wsstring

Workspace ID override.

-n, --limitnumber

Maximum number of results. Defaults to 50.

stash history agents[--ws ID]

List distinct agent names that have logged events in this workspace.

--wsstring

Workspace ID override.

stash history transcript<session_id> [--ws ID] [--save PATH]

Fetch a full session transcript and print or save it. Transcripts are stored gzipped on the server and decompressed automatically.

<session_id>stringREQUIRED

ID of the session.

--wsstring

Workspace ID override.

--savepath

Save the transcript to a file instead of printing.

Tables

stash tables list[--ws ID] [--all] [--personal]

List tables in the current workspace.

--wsstring

Workspace ID override.

--allflag

Include tables from all workspaces.

--personalflag

Show only personal tables.

stash tables create<name> [--ws ID] [--columns JSON]

Create a new table with optional column definitions.

<name>stringREQUIRED

Name for the table.

--wsstring

Workspace ID override.

--columnsJSON

Column definitions as a JSON array of {name, type, options?}.

stash tables update<table_id> [--name TEXT] [--description TEXT]

Update a table's name or description.

<table_id>stringREQUIRED

ID of the table.

--wsstring

Workspace ID override.

--namestring

New table name.

--descriptionstring

New table description.

stash tables schema<table_id>

Show a table's column schema.

<table_id>stringREQUIRED

ID of the table.

--wsstring

Workspace ID override.

stash tables rows<table_id> [--sort COL] [--filter COL]

Fetch rows from a table. Sort and filter accept column names, which are auto-resolved.

<table_id>stringREQUIRED

ID of the table.

--sortstring

Column name to sort by.

--filterstring

Column name to filter on.

--wsstring

Workspace ID override.

stash tables insert<table_id> <data_json>

Insert a new row. Data is a JSON object with column names as keys.

<table_id>stringREQUIRED

ID of the table.

<data_json>JSONREQUIRED

Row data as a JSON object.

--wsstring

Workspace ID override.

stash tables import<table_id> <file> [--format csv|json]

Bulk import rows from a file. Auto-chunks into batches of 5000. CSV uses the first row as column headers. Supports piping: cat data.csv | stash tables import <id> --format csv.

<table_id>stringREQUIRED

ID of the table.

<file>pathREQUIRED

Path to the import file.

--formatstring

File format: "csv" or "json". Auto-detected if omitted.

stash tables update-row<table_id> <row_id> <data_json>

Update an existing row with a partial merge. Data is a JSON object with column names as keys.

<table_id>stringREQUIRED

ID of the table.

<row_id>stringREQUIRED

ID of the row to update.

<data_json>JSONREQUIRED

Updated row data as a JSON object.

--wsstring

Workspace ID override.

stash tables delete-row<table_id> <row_id>

Delete a row from a table.

<table_id>stringREQUIRED

ID of the table.

<row_id>stringREQUIRED

ID of the row to delete.

--wsstring

Workspace ID override.

stash tables add-column<table_id> <name> [--type text] [--options TEXT]

Add a column to a table.

<table_id>stringREQUIRED

ID of the table.

<name>stringREQUIRED

Column name.

--typestring

Column type. Defaults to "text".

--optionsstring

Comma-separated options for select/multiselect columns.

--wsstring

Workspace ID override.

stash tables delete-column<table_id> <column_id>

Delete a column from a table.

<table_id>stringREQUIRED

ID of the table.

<column_id>stringREQUIRED

Column ID (col_xxx) or column name.

--wsstring

Workspace ID override.

stash tables count<table_id>

Count rows in a table, optionally with filters.

<table_id>stringREQUIRED

ID of the table.

--wsstring

Workspace ID override.

stash tables export<table_id>

Export all rows from a table as CSV.

<table_id>stringREQUIRED

ID of the table.

--wsstring

Workspace ID override.

stash tables delete<table_id> [-y]

Delete a table and all its data.

<table_id>stringREQUIRED

ID of the table.

-y, --yesflag

Skip confirmation prompt.

--wsstring

Workspace ID override.

Files

stash files upload<path> [--ws ID]

Upload a file to a workspace or to your personal files.

<path>pathREQUIRED

Path to the file.

--wsstring

Workspace ID. Omit to upload as a personal file.

stash files list[--ws ID]

List files in a workspace or your personal files.

--wsstring

Workspace ID. Omit to list personal files.

stash files rm<file_id>

Delete a file.

<file_id>stringREQUIRED

ID of the file to delete.

stash files text<file_id>

Print extracted text for a file (PDF, image OCR, or plain text).

<file_id>stringREQUIRED

ID of the file.

Invites

stash invite[--ws ID] [--uses N] [--days N]

Create a magic-link invite — a single-use, TTL-bounded token for zero-friction workspace onboarding.

--wsstring

Workspace ID to create the invite for.

--usesnumber

Maximum times the link can be redeemed. Defaults to 1.

--daysnumber

Days until the link expires. Defaults to 7.

stash invite list[--ws ID]

List active invite tokens for a workspace.

--wsstring

Workspace ID override.

stash invite revoke<token_id> [--ws ID]

Revoke an invite token so it can no longer be redeemed.

<token_id>stringREQUIRED

ID of the invite token to revoke.

--wsstring

Workspace ID override.

Keys

stash keys list

List your active API keys (one per device / login).

stash keys revoke<key_id>

Revoke an API key by ID. Any device using it will receive a 401 on the next call.

<key_id>stringREQUIRED

ID of the key to revoke.

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 for all supported coding agents on your PATH.

stash enable

Re-enable activity streaming for the current repository.

stash disable

Stop streaming for this repo without touching the committed manifest.

stash settings[--json]

Open the interactive settings page.

--jsonflag

Print a read-only snapshot of settings instead of opening the interactive page.