Shaped CLI

A reference for the Shaped command line interface, focused on the most common workflows.

Install

The CLI is a Python package. Use pip to install it:

pip install shaped

Authentication and configuration

Use shaped init to connect the CLI to your Shaped account.

shaped init --api-key YOUR_API_KEY

Shell completion and help

To make the CLI easier to use:

• Install shell completion for your current shell:

  shaped --install-completion

• Preview completion script without installing:

  shaped --show-completion

• Get help for any command:

  shaped --help
  shaped create-engine --help
  shaped query --help

These commands show the full list of options and flags if you need more detail than this reference.

Table and data management

Shaped stores your data in tables. The typical workflow is:

1. Create a table for your domain data.
2. Insert data from a file (CSV / JSONL).
3. Connect the table in your engine’s data block.

These commands mirror the table setup you see in the Quickstart and Hybrid Search docs.

Create a table from a data file

Create a table and immediately load data from a local file:

shaped create-table-from-uri \
  --name pixar_movies \
  --uri ./data/pixar_movies.csv

Required flags

• --name TABLE_NAME: Name of the table in Shaped (e.g. pixar_movies).
• --uri PATH_OR_URI: Local file path or remote URI of the data file.

Create a table with an explicit schema

If you want to control the schema (like the CUSTOM schemas in the examples), use create-table with a schema file:

shaped create-table --config table.yaml

Required flags

• --config PATH: Path to a table config file that defines schema_type, name, and column_schema.

Insert data into an existing table

Insert rows from a file into an existing table:

shaped table-insert \
  --name pixar_movies \
  --file ./data/pixar_movies.csv \
  --type csv

Required flags

• --name TABLE_NAME: Existing table name.
• --uri PATH_OR_URI: File containing rows (CSV / JSONL).

This is the CLI equivalent of using client.insert_table_rows("pixar_movies", records) in the Python examples.

Inspect, list, and delete tables

List all tables:

shaped list-tables

View configuration for a single table:

shaped view-table --name pixar_movies

Delete a table:

shaped delete-table --name pixar_movies

Required flags

• --name TABLE_NAME: Table to inspect or delete.

Seed demo tables

Like engines, you can seed demo tables:

shaped table-seeds
shaped table-seed --name NAME_FROM_LIST

Required flags

• --name SEED_NAME: One of the names shown in shaped table-seeds.

Engine management

Engines define how your data is indexed, trained, and served.

Create an engine from a config file

Use create-engine to create a new engine from a YAML configuration:

shaped create-engine --config engine.yaml

Required flags

• --config PATH: Path to an engine config file (see engine-recipes for examples of data, index, training, deployment, and queries blocks).

Learn more about configuring engines - Engine basics

Update an existing engine

Use update-engine when you change your engine config (for example, adding hybrid search or a new embedding):

shaped update-engine --name hybrid_search --config engine.yaml

Required flags

• --name ENGINE_NAME: The name of the engine to update (e.g. semantic_search, hybrid_search).
• --config PATH: Updated engine config file.

Inspect and list engines

List all engines in your account:

shaped list-engines

View a specific engine’s configuration (useful to compare to examples in engine-recipes):

shaped view-engine --name hybrid_search

Required flags

• --name ENGINE_NAME: Engine to inspect.

Delete an engine you no longer need:

shaped delete-engine --name hybrid_search

Required flags

• --name ENGINE_NAME: Engine to delete.

Seed demo engines

Use a pre-built demo engine to explore Shaped quickly:

shaped engine-seeds
shaped engine-seed --name NAME_FROM_LIST

Required flags

• --name SEED_NAME: One of the names shown in shaped engine-seeds.

Views

Views let you define reusable SQL transformations over existing tables. They are handy when you want to:

• Normalize IDs to item_id / user_id.
• Filter or join data before the engine sees it.

Common commands:

shaped create-view --config view.yaml
shaped list-views
shaped view-view --name my_view
shaped update-view --name my_view --config view.yaml
shaped delete-view --name my_view

Required flags

• --config PATH: For create-view / update-view.
• --name VIEW_NAME: For view-view, update-view, and delete-view.

Your engine data block can then point to a view instead of a raw table (see the query-based examples in engine-recipes).

Running queries with the CLI

Once your engine is created and indexed, you can run ad-hoc and saved queries directly from the CLI.

Ad-hoc ShapedQL queries

To experiment with queries like the ShapedQL examples in the Query Reference, use query:

shaped query \
  --engine hybrid_search \
  --query-file query.sql \
  --params '{"query": "Incredibles"}'

Required flags

• --engine ENGINE_NAME: Engine to query (e.g. hybrid_search).
• --query-file PATH: File containing a ShapedQL query (see shapedql docs for examples).

Common optional flags

• --params JSON: JSON object of parameter values (e.g. {"query": "Incredibles"}), matching $parameters.* in your query.

Execute saved queries

If your engine config defines saved queries in the queries block (for example, search_products or personalized_feed from the engine recipes), you can execute them by name:

shaped execute-saved-query \
  --engine hybrid_search \
  --name search_products \
  --params '{"query_text": "Incredibles"}'

Required flags

• --engine ENGINE_NAME: Engine that owns the saved query.
• --name QUERY_NAME: Saved query name from the engine config.

Common optional flags

• --params JSON: Parameters expected by the query (e.g. query_text, user_id, item_id).

List all saved queries on an engine:

shaped list-saved-queries --engine hybrid_search

View the definition of a saved query (helpful when matching it with the queries block in YAML):

shaped view-saved-query \
  --engine hybrid_search \
  --name search_products

Required flags

• --engine ENGINE_NAME
• --name QUERY_NAME