Getting Started

Save an issue, read it back, and see Silo reject an invalid value.

Before you start

Install Silo globally:

pnpm add --global @silo-ai/silo

You need:

  • Node.js 24.10.0 or newer
  • SQLite 3.37.0 or newer
  • A Git worktree

Run the commands below from the repository that should own the data. A Git remote is optional. Check which local database Silo will use:

silo status

The Database row shows a path outside the repository. In a new repository, State is absent; creating the first table will create the database.

Create an issues table

Each row in issues will hold one piece of work for an agent to pick up later. Save this table definition as issues-table.json. This is a command input file; you do not need to commit it to Git:

{
  "name": "issues",
  "comment": "One actionable repository issue that agents read before planning work.",
  "columns": [
    {
      "name": "id",
      "type": "text/uuid",
      "nullable": false,
      "comment": "Stable identifier generated by Silo."
    },
    {
      "name": "title",
      "type": "text",
      "nullable": false,
      "comment": "Short description of the issue."
    }
  ],
  "primary_key": ["id"],
  "policies": [{ "type": "generated_identity", "column": "id", "strategy": "uuid" }]
}

Create the table and check its definition:

silo table create --file issues-table.json
silo table show issues

The first command reports Table Created. The second shows:

  • An id column containing a UUID, generated by Silo
  • A title column containing text
  • Neither column allows null

Add one row

Supply a title. Silo generates the ID:

printf '%s\n' '{"title":"Document the release process"}' | silo row add issues

The command prints the saved row. Your generated ID will differ:

# Rows Added

| id | title |
| --- | --- |
| ea4b7f49-b18b-4596-b9b2-93c4b249c84e | Document the release process |

The row is now saved locally and remains available after the agent session ends. It has not been shared with another machine.

Read the row back

silo sql 'SELECT id, title FROM issues ORDER BY title'

The Query Result shows the issue you just added. SQL is read-only; use Silo's row commands to change data.

See a rejected write

The schema says that title must be a JSON string. Try a number instead:

printf '%s\n' '{"title":42}' | silo row add issues

The command fails with a nonzero exit status and this error:

# Error

| Path | Code | Message |
| --- | --- | --- |
| title | `invalid_semantic_value` | text requires a JSON string. |

The row is rejected before it is committed. Verify that the failed command did not add a second row:

silo row list issues --limit 20

The list should still contain only Document the release process. The schema requires a text title, and Silo rejected the number without saving another row.

Choose your next step