CLI Reference

A command-line interface for managing Stash from your terminal — push session 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 sessions 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]

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.

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

List workspaces you belong to.

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

Create a new workspace.

<name>stringREQUIRED

Name for the workspace.

--descriptionstring

Workspace description.

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.

Files

stash files pages[--ws ID] [--all]

List pages in the current workspace.

--wsstring

Workspace ID override.

--allflag

Include pages from all workspaces.

stash files tree[--ws ID]

Show the folder and page tree for a workspace.

--wsstring

Workspace ID override.

stash files create-folder<name> [--ws ID] [--parent FOLDER_ID]

Create a folder in the files.

<name>stringREQUIRED

Folder name.

--wsstring

Workspace ID override.

--parentstring

Parent folder ID.

stash files add-page<name> [--ws ID] [--folder FOLDER_ID] [--content '...']

Add a new page to the files.

<name>stringREQUIRED

Page title.

--folderstring

Folder ID.

--contentstring

Initial page content.

stash files read-page<page_id> [--ws ID]

Read a page.

<page_id>stringREQUIRED

ID of the page.

--wsstring

Workspace ID override.

stash files edit-page<page_id> [--ws ID] --content '...'

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

<page_id>stringREQUIRED

ID of the page.

--wsstring

Workspace ID override.

--contentstring

New page content. Reads from stdin if omitted.

Sessions

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

Push a new event to the workspace session 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 sessions query[--agent X] [--type Y] [-n 50] [--all]

Query recent session 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 sessions search<query> [--ws ID] [-n 50]

Full-text search across workspace sessions.

<query>stringREQUIRED

Search query.

--wsstring

Workspace ID override.

-n, --limitnumber

Maximum number of results. Defaults to 50.

stash sessions agents[--ws ID]

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

--wsstring

Workspace ID override.

stash sessions 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.

Uploaded 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.