Command line interface

This section documents the dataspine CLI. Two binaries are distributed in every release archive: dataspine (the unified platform + compile tool) and spinec (the Spine language compiler / LSP server).

Quick links

• Root command: dataspine
• Local commands (no network required):
  • dataspine compile — compile .spine sources → dataproduct-definition JSON
  • dataspine check — report diagnostics with structured JSON/YAML output
  • dataspine init — scaffold a new data product workspace
• Remote commands (require authentication, connect via management data product API):
  • dataspine org — create / describe / update / delete / list organizations
  • dataspine data-product — CRUD for data products and their versions
  • dataspine dp-profile — describe / update / clear data product profiles
  • dataspine application — CRUD for applications; manage AWS/SSH principal associations
  • dataspine principal — CRUD for principals and IdP associations
  • dataspine permission — grant / revoke / list permissions
  • dataspine trigger — manage outlet Lambda triggers and bindings
  • dataspine observability — query logs, traces, and metrics (unstable)
• Agent tooling:
  • dataspine mcp — start a local stdio MCP server for AI agents
• Auth & tooling:
  • dataspine login / dataspine logout
  • dataspine artifacts → dataspine artifacts login
  • dataspine sts → token exchange commands
  • dataspine profile — manage named profiles

Global options

All commands support these options on the root command:

• -o, --output-type <TYPE>: text (default), json, yaml — all remote commands return machine-parseable JSON/YAML when requested.
• -a, --auth <AUTH>: env (default), token:<token>, aws-sigv4:<principal_id>, ssh-pop:<principal_id>[:<private_key>]
• --non-interactive (env DATASPINE_NON_INTERACTIVE): disable all prompts; implied when stdin is not a TTY. Missing required flags produce structured errors instead of interactive prompts.
• --profile <PROFILE> (env DATASPINE_PROFILE): named credential profile to use.

See dataspine for details and examples.

dataspine mcp

dataspine mcp starts a local Model Context Protocol (MCP) server over stdio (JSON-RPC). AI agents (Claude, Cursor, etc.) can connect to it and call any Dataspine operation as a tool call, using the authenticated profile configured at startup.

Starting the server

# use an already-authenticated profile
dataspine --profile prod mcp

# use a static token (e.g. in CI)
dataspine --auth token:<token> mcp

# non-interactive mode (implied when stdin is not a TTY)
dataspine --profile prod --non-interactive mcp

All log output is written to stderr; stdout is reserved for the MCP JSON-RPC stream.

Agent client configuration

Add the following to your agent's MCP config (e.g. ~/.cursor/mcp.json or mcp_settings.json):

{
  "mcpServers": {
    "dataspine": {
      "command": "dataspine",
      "args": ["--profile", "<profile>", "mcp"]
    }
  }
}

Replace <profile> with the name of your configured profile (e.g. prod, staging, default). You can omit --profile to use the default profile configured in ~/.dataspine/config.yaml.

Tool surface

The MCP server exposes ~40 tools with full parity to the Admin API:

Domain	Tools
Organizations	org_list, org_create, org_describe, org_update, org_delete, org_set_default_profile
Data Products	data_product_list, data_product_create, data_product_describe, data_product_delete
Data Product Versions	data_product_version_list, data_product_version_describe, data_product_version_delete, data_product_version_docs
Data Product Profiles	dp_profile_describe, dp_profile_update, dp_profile_clear
Applications	application_list, application_create, application_update, application_delete
AWS Principal Assoc.	application_aws_principal_add, application_aws_principal_remove, application_aws_principal_list
SSH Principal Assoc.	application_ssh_principal_add, application_ssh_principal_remove, application_ssh_principal_list
Principals	principal_list, principal_create, principal_describe, principal_delete
Principal Assoc.	principal_association_create, principal_association_delete, principal_association_list
Permissions	permission_grant, permission_revoke, permission_list
Outlet Lambda Triggers	trigger_list, trigger_create, trigger_update, trigger_delete, trigger_bind, trigger_unbind, trigger_list_bindings
Observability (unstable)	observability_logs, observability_traces, observability_trace, observability_metrics, observability_list_metrics
Local (offline)	compile, check, validate, init

Local tools (compile, check, validate, init) do not require network access or authentication and work offline against .spine source files on disk.

spinec

The spinec binary provides the Spine language compiler and LSP server. It is bundled in the same release archive as dataspine and installed alongside it.

• spinec compile — compile .spine sources (identical functionality to dataspine compile)
• spinec diagnose — report diagnostics (text rendering via ariadne)
• spinec lsp — start the LSP server on stdio (used by VS Code / Cursor extensions)

Configure your editor's LSP extension with dataspine.lsp.serverPath: spinec.

Configuration

The CLI loads configuration from:

• Config file: ~/.dataspine/config.yaml (default), or override via DATASPINE_CONFIG
• Environment variables: DATASPINE_* (e.g. DATASPINE_ENDPOINT, DATASPINE_ENDPOINTS_STS, DATASPINE_ENDPOINTS_ARTIFACTS, DATASPINE_ENDPOINTS_MANAGEMENT)

Authentication via environment variables:

• DATASPINE_TOKEN: Use this bearer token directly.
• DATASPINE_EXCHANGE_TOKEN: Treated as an input token for token exchange when using --auth env.