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.

Virtual filesystem

Use stash vfs when an agent needs to browse workspace files, pages, sessions, stashes, and tables through one filesystem-shaped interface without mounting anything into the OS.

stash vfs ls /
stash vfs "find /workspaces -maxdepth 3 -type f"
stash vfs "rg 'database migration' /workspaces"
stash vfs "cat '/workspaces/<workspace>/README.md' | sed -n '1,80p'"

stash vfs[--ws ID] [--cwd PATH] "command"

Run bash-shaped read and write commands against the virtual Stash tree.

--wsstring

Expose one workspace by ID. By default all accessible workspaces are exposed.

--cwdstring

Virtual working directory. Defaults to /.

commandstring

Bash-shaped command such as ls, find, rg, cat, sed, tee, or redirection.

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.

To search sessions, use the unified stash search with --source sessions (see Sources & search below). It replaces the old per-resource search commands.

stash sessions folders[--ws ID]

List session folders — shareable groupings of sessions.

--wsstring

Workspace ID override.

stash sessions new-folder<name> [--ws ID]

Create a session folder.

<name>stringREQUIRED

Folder name.

--wsstring

Workspace ID override.

stash sessions assign<session_row_id> [--folder ID]

Move a session into a session folder, or omit --folder to move it back to the ungrouped root.

<session_row_id>stringREQUIRED

The session row id to move.

--folderstring

Target folder id. Omit to ungroup.

--wsstring

Workspace ID override.

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.

Sources & search

A source is anything the agent can read, exposed as a virtual file system: the two native sources — files and sessions — plus your connected sources (GitHub, Google Drive, Notion, Slack, Granola). Pick a source like a drive, browse it by path, read a document, or search one source — or everything at once.

stash sources ls[--ws ID]

List every source you can read here: the native files and sessions sources plus your connected sources. Each row prints a source handle to use with the other commands.

--wsstring

Workspace ID override.

stash sources add<source_type> [--ref REF] [--name NAME]

Connect a source. Slack and Granola resolve their reference from your connected token; the others need a --ref (e.g. a repo 'owner/name').

<source_type>stringREQUIRED

github_repo | google_drive | notion | slack | granola.

--refstring

External reference, e.g. a repo 'owner/name'.

--namestring

Display name for the source.

--wsstring

Workspace ID override.

stash sources browse<source> [path] [--ws ID]

List a source's entries like a file system.

<source>stringREQUIRED

A source handle from stash sources ls.

pathstring

Path prefix (connected sources only).

--wsstring

Workspace ID override.

stash sources read<source> <ref> [--ws ID]

Read one document from a source.

<source>stringREQUIRED

A source handle from stash sources ls.

<ref>stringREQUIRED

Page id (files), session id (sessions), or document path (connected sources).

--wsstring

Workspace ID override.

stash sources sync<source_id> [--ws ID]

Trigger an immediate re-index of a connected source you own.

<source_id>stringREQUIRED

ID of the connected source.

--wsstring

Workspace ID override.

stash sources rm<source_id> [--ws ID]

Disconnect a source you own. Its indexed documents are removed.

<source_id>stringREQUIRED

ID of the connected source.

--wsstring

Workspace ID override.

stash search<query> [--source HANDLE] [--ws ID] [-n 20]

Search across everything you can see — files, sessions, and connected sources. Pass --source to scope to one; omit it to search everything.

<query>stringREQUIRED

Search query.

--sourcestring

Scope to one source handle (from stash sources ls). Omit to search everything.

-n, --limitnumber

Maximum number of results. Defaults to 20.

--wsstring

Workspace ID override.

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.

Cartridges

A Cartridge is a shareable bundle of pages, sessions, tables, and files — the unit you publish to a public link or share with specific people. (Cartridges are what earlier versions called “Stashes”; the stash CLI name is unchanged.)

stash cartridges list[--ws ID]

List Cartridges in the workspace.

--wsstring

Workspace ID override.

stash cartridges create<title> [--public/--private] [--discover] [--items JSON]

Create a Cartridge. Pass --items as JSON to attach resources up front.

<title>stringREQUIRED

Cartridge title.

--public/--privateflag

Visibility. --public mints a shareable link.

--discoverflag

List a public Cartridge in the Discover catalog (requires --public).

--itemsJSON

Items as a JSON array of {object_type, object_id}.

--wsstring

Workspace ID override.

stash cartridges members<cartridge_id>

List the people granted access to a Cartridge.

<cartridge_id>stringREQUIRED

ID of the Cartridge.

stash cartridges add-member<cartridge_id> <user_id> [--permission read]

Grant a user access to a Cartridge.

<cartridge_id>stringREQUIRED

ID of the Cartridge.

<user_id>stringREQUIRED

The user to grant access.

--permissionstring

read | write | admin. Defaults to read.

stash cartridges remove-member<cartridge_id> <user_id>

Revoke a user's access to a Cartridge.

<cartridge_id>stringREQUIRED

ID of the Cartridge.

<user_id>stringREQUIRED

The user to revoke.

stash cartridges invites

List Cartridge invites pending for you — Cartridges shared with you, awaiting accept or dismiss.

stash cartridges dismiss-invite<invite_id>

Dismiss a pending Cartridge invite.

<invite_id>stringREQUIRED

ID of the pending invite.

stash cartridges snapshot-source<cartridge_id> --source ID --path PATH [--ws ID]

Copy a point-in-time snapshot of one connected-source document into the Cartridge as a page, so the bundle stays self-contained.

<cartridge_id>stringREQUIRED

ID of the Cartridge.

--sourcestringREQUIRED

Connected-source id (from stash sources ls).

--pathstringREQUIRED

Document path within the source.

--wsstring

Workspace ID override.

stash cartridges add-external<slug> [--ws ID]

Fork a public Cartridge into a workspace by its slug.

<slug>stringREQUIRED

Public Cartridge slug.

--wsstring

Workspace ID override.

stash cartridges delete<cartridge_id>

Delete a Cartridge.

<cartridge_id>stringREQUIRED

ID of the Cartridge.

Share a single object — a folder, page, file, session, or table — with a specific person by email. If they don't have an account yet the share is recorded as pending and converts when they sign up. (To share a whole bundle, use a Cartridge above.)

stash shares ls<object_type> <object_id>

List who an object is shared with.

<object_type>stringREQUIRED

folder | page | file | session | table.

<object_id>stringREQUIRED

ID of the object.

stash shares add<object_type> <object_id> <email> [--permission read]

Share an object with a person by email.

<object_type>stringREQUIRED

folder | page | file | session | table.

<object_id>stringREQUIRED

ID of the object.

<email>stringREQUIRED

Recipient email (pending until they sign up).

--permissionstring

read | write | admin. Defaults to read.

stash shares rm<object_type> <object_id> <principal_id> [--principal-type user]

Revoke a person's access to an object.

<object_type>stringREQUIRED

folder | page | file | session | table.

<object_id>stringREQUIRED

ID of the object.

<principal_id>stringREQUIRED

The user id to revoke (from stash shares ls).

--principal-typestring

Principal kind. Defaults to "user".

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.

CLI Reference

Install

First-time setup

Virtual filesystem

Authentication

Workspaces

Files

Sessions

Sources & search

Tables

Uploaded Files

Cartridges

Shares

Invites

Keys

Streaming & hooks