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.

Install

uv tool install stashai

First-time setup

Run the interactive setup wizard. It configures the API endpoint, authenticates you through the browser, and sets up your Stash — 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 Stash through one filesystem-shaped interface without mounting anything into the OS. Your Stash exposes files, sessions, skills, tables, and sources — the last surfacing every connected integration (Gmail, GitHub, Slack, Jira, …) as read-only documents you can ls, cat, and grep.

stash vfs ls /
stash vfs "find /me -maxdepth 3 -type f"
stash vfs "rg 'database migration' /me"
stash vfs --cwd "/me/sources" "rg 'incident' ."

stash vfs[--cwd PATH] "command"

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

--cwdstring

Virtual working directory. Defaults to /.

commandstring

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

Authentication

stash signin[--api <base_url>] [--api-key <key>] [--non-interactive]

Authenticate this machine. With no flags it runs the browser flow: on first run it also picks the endpoint (managed or self-host) and offers to install streaming hooks for your coding agents. On SSH/headless it prints a URL to open instead of launching a browser. Pass --api-key to store a pre-minted key directly (no browser) on an unattended, browser-less machine — typically a self-hosted CI runner; get the key from your self-hosted instance's API-key page.

--apistring

Base URL of the Stash server. Override for self-hosted deployments.

--api-keystring

A pre-minted key to store directly, skipping the browser. For unattended, browser-less machines.

--non-interactiveflag

Skip the setup wizard; just authenticate. Implied when stdin isn't a terminal.

Setting STASH_API_KEY / STASH_URL in the environment authenticates CLI commands for CI and scripts — but it does not reach the streaming hooks, which read ~/.stash/config.json. To make an unattended machine stream, use stash signin --api-key. Change the endpoint or streaming agents later from stash settings.

stash whoami

Display the currently authenticated user.

stash disconnect

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

stash settings[--json]

Interactive settings page — change the endpoint, toggle which agents stream, and view config. Pass --json for a read-only snapshot.

--jsonflag

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

After stash connect, your defaults are stored. Change the endpoint any time from stash settings, or set STASH_API_KEY / STASH_URL as environment variables for CI and scripts.

Files

stash files pages

List pages in your Stash.

stash files tree

Show the folder and page tree for your Stash.

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

Create a folder in the files.

<name>stringREQUIRED

Folder name.

--parentstring

Parent folder ID.

stash files add-page<name> [--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>

Read a page.

<page_id>stringREQUIRED

ID of the page.

stash files edit-page<page_id> --content '...'

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

<page_id>stringREQUIRED

ID of the page.

--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 your session stream.

<content>stringREQUIRED

Event content to push.

--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]

Query recent session events with optional filters.

--agentstring

Filter by agent identifier.

--typestring

Filter by event type.

-n, --limitnumber

Maximum number of results. Defaults to 50.

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

List session folders — shareable groupings of sessions.

stash sessions new-folder<name>

Create a session folder.

<name>stringREQUIRED

Folder name.

stash sessions agents

List distinct agent names that have logged events in your Stash.

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

--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, Gmail, 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

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.

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

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

<source_type>stringREQUIRED

--refstring

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

--namestring

Display name for the source.

stash sources browse<source> [path]

List a source's entries like a file system.

<source>stringREQUIRED

A source handle from stash sources ls.

pathstring

Path prefix (connected sources only).

stash sources read<source> <ref>

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

stash sources sync<source_id>

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

<source_id>stringREQUIRED

ID of the connected source.

stash sources rm<source_id>

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

<source_id>stringREQUIRED

ID of the connected source.

stash search<query> [--source HANDLE] [-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.

Tables

stash tables list

List tables in your Stash.

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

Create a new table with optional column definitions.

<name>stringREQUIRED

Name for the table.

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

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

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.

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.

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.

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.

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.

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.

stash tables count<table_id>

Count rows in a table, optionally with filters.

<table_id>stringREQUIRED

ID of the table.

stash tables export<table_id>

Export all rows from a table as CSV.

<table_id>stringREQUIRED

ID of the table.

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.

Uploaded Files

stash upload<path> [--skill TITLE]

Upload a single file (Markdown/HTML become pages, everything else a binary file) or a folder into your Stash. Pass --skill to also bundle it into a shareable Skill.

<path>pathREQUIRED

File or directory to upload.

--skillstring

Also publish the upload as a Skill with this title.

stash files list

List your files.

stash files text<file_id>

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

<file_id>stringREQUIRED

ID of the file.

Object operations

One set of verbs across every object type. Pass items as type:id tokens (e.g. page:abc, file:def, session:ghi); each verb accepts several at once.

stash rm<type:id>... [--permanent]

Move pages, files, or sessions to trash. Pass --permanent to skip the trash window and delete immediately.

<type:id>stringREQUIRED

Items to delete, e.g. page:<id> session:<id>.

--permanentflag

Delete immediately instead of trashing.

stash restore<type:id>...

Restore pages, files, or sessions from trash.

<type:id>stringREQUIRED

Items to restore, e.g. page:<id> file:<id>.

stash mv<type:id>... (--to-folder ID | --to-root)

Move pages, files, folders, tables, or sessions into a folder, or to the root.

<type:id>stringREQUIRED

Items to move.

--to-folderstring

Target folder id.

--to-rootflag

Move to the root.

stash cp<type:id>... [--to-folder ID]

Duplicate pages, files, or folders as 'Copy of <name>'.

<type:id>stringREQUIRED

Items to copy.

--to-folderstring

Target folder id for the copies.

Skills

A Skill is a special folder — one containing a SKILL.md — of pages, files, and tables. Publishing a skill makes it publicly readable at its link (optionally listed in Discover); to share privately with a specific person, share its folder like any other folder. (The stash CLI name is unchanged.)

stash skills list

List Skills in your Stash.

stash skills create<name> [--public] [--discover]

Create a skill: a folder with a SKILL.md template. Pass --public to publish immediately.

<name>stringREQUIRED

Skill name (becomes the folder name).

--publicflag

Publish immediately and mint a shareable link.

--discoverflag

List the public Skill in the Discover catalog (requires --public).

stash skills publish<folder_id> [--discover]

Publish an existing skill folder: mint its share record and print the public URL.

<folder_id>stringREQUIRED

The skill folder to publish.

--discoverflag

List the public Skill in Discover.

stash skills snapshot-source<skill_id> --source ID --path PATH

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

<skill_id>stringREQUIRED

ID of the Skill.

--sourcestringREQUIRED

Connected-source id (from stash sources ls).

--pathstringREQUIRED

Document path within the source.

stash skills fork<slug>

Fork a public Skill: deep-copy its folder into your Stash.

<slug>stringREQUIRED

Public Skill slug.

stash skills unpublish<skill_id>

Stop sharing a Skill: delete its publish record. The folder stays.

<skill_id>stringREQUIRED

ID of the published Skill.

stash skills install<slug> [--project] [--dir PATH]

Install a public Skill into your agent's skills directory. Installed skills are tracked and auto-update whenever skills sync runs (the plugin runs one at every session start); a one-shot notice at the next session start lists what changed.

<slug>stringREQUIRED

Public Skill slug.

--projectflag

Install into ./.claude/skills (this repo only) instead of ~/.claude/skills.

--dirstring

Custom skills directory.

stash skills uninstall<slug-or-name> [--project] [--dir PATH]

Remove an installed Skill and stop auto-updating it.

<slug-or-name>stringREQUIRED

The installed skill's slug or folder name.

stash skills follow[--project] [--dir PATH]

Auto-install skills people share with you. New shared skills land at the next skills sync and update like any installed skill; stash skills unfollow turns it off (already-installed skills stay).

stash skills sync[--project] [--dir PATH]

Two-way sync between the local skills directory and your Stash: your own skills three-way sync (conflicts are skipped loudly), installed skills refresh from their cloud copy. The plugin runs this automatically at session start.

MCP servers

Register MCP servers once and every agent gets them: your cloud agent's .mcp.json is refreshed on each turn, and stash tools install writes an entry into a local repo's .mcp.json. Header and env secrets are stored encrypted.

stash tools add<name> (--url URL | --command CMD) [--header K=V] [--env K=V]

<name>stringREQUIRED

Server name, unique in your account.

--urlstring

HTTP MCP endpoint (remote transport).

--commandstring

Command line to launch a stdio server.

--headerstring

HTTP header as KEY=VALUE (repeatable; stored encrypted).

--envstring

Env var for stdio servers as KEY=VALUE (repeatable; stored encrypted).

stash tools install<name>

Write a registered server into this repo's .mcp.json (merged — your own entries are never touched; re-runs are idempotent).

<name>stringREQUIRED

A server from stash tools list.

stash tools remove<name>

Delete a registered MCP server.

<name>stringREQUIRED

Server name.

Workspaces

A workspace is a shared team scope: members' sessions, events, and searches can run against it instead of their personal Stash. Switching applies everywhere on your machine — the CLI, every agent plugin, and the MCP server. Team workspaces are set up for you — email sam@joinstash.ai.

stash workspace list

List workspaces you belong to, marking the active scope.

stash workspace switch<name>

Route sessions, events, transcripts, and searches to this workspace — or back with stash workspace switch personal.

<name>stringREQUIRED

Workspace name or domain, or 'personal'.

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 folder of related work, convert it to a Skill.)

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

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

Files

Sessions

Sources & search

Tables

Uploaded Files

Object operations

Skills

MCP servers

Workspaces

Shares

Keys

Streaming & hooks