cli

Seren CLI

Command-line interface for managing SerenAI's SerenDB databases, projects, branches, and agent commerce.

Installation

From Source (Recommended)

git clone https://github.com/serenorg/seren.git
cd seren
cargo install --path cli

From Git (No Clone)

cargo install --git https://github.com/serenorg/seren.git --package seren-cli

Pre-built Binaries

Download pre-built binaries from GitHub Releases (tagged versions): https://github.com/serenorg/seren/releases

Quick Start

# Authenticate with SerenAI
seren auth login

# List your projects
seren projects list

# Create a new project
seren projects create --name my-app --region aws-us-east-1

# Get connection string
seren projects connection-uri <project-id>

Authentication

OAuth Login (Recommended)

seren auth login

Opens your browser for secure OAuth authentication.

API Key

# Set via environment variable
export SEREN_API_KEY=seren_your_api_key_here
seren projects list

# Or pass directly
seren --api-key seren_your_api_key projects list

Check Status

seren auth status
seren me

Commands

Projects

seren projects list
seren projects get <project-id>
seren projects create --name my-project --region aws-us-east-1
seren projects create --name my-project --region aws-us-east-1 --psql  # connect via psql after creation
seren projects update <project-id> --name new-name
seren projects connection-uri <project-id>
seren projects connection-uri <project-id> --pooled --branch-id <id>
seren projects delete <project-id>
seren projects delete <project-id> --yes

Branches

seren branches --project-id <id> list
seren branches --project-id <id> get <branch-id>
seren branches --project-id <id> create --name feature-branch
seren branches --project-id <id> create --name restore-branch \
  --parent <parent-id> --parent-timestamp "2025-01-15T10:00:00Z"
seren branches --project-id <id> create --name temp-branch --expires-in 7d
seren branches --project-id <id> create --name schema-branch --schema-only
seren branches --project-id <id> connection-string <branch-id>
seren branches --project-id <id> connection-string <branch-id> --pooled
seren branches --project-id <id> rename <branch-id> --name new-name
seren branches --project-id <id> set-default <branch-id>
seren branches --project-id <id> set-expiration <branch-id> --expires-at "2025-12-31T23:59:59Z"
seren branches --project-id <id> schema-diff \
  --base-branch-id <id> --compare-branch-id <id>
seren branches --project-id <id> reset <branch-id>
seren branches --project-id <id> restore <branch-id> \
  --source ^self --preserve-under-name backup \
  --timestamp "2025-01-15T10:00:00Z"
seren branches --project-id <id> delete <branch-id>

Databases & Roles

# Databases
seren databases --project-id <id> --branch-id <id> list
seren databases --project-id <id> --branch-id <id> create --name mydb
seren databases --project-id <id> --branch-id <id> delete <db-id>

# List all databases across projects
seren database list
seren database list --project-id <id>

# Roles
seren roles --project-id <id> --branch-id <id> list
seren roles --project-id <id> --branch-id <id> create --name myrole
seren roles --project-id <id> --branch-id <id> reset-password --id <role-id> --password newpass
seren roles --project-id <id> --branch-id <id> reveal-password --name <role-name>
seren roles --project-id <id> --branch-id <id> delete <role-id>

Endpoints

seren endpoints --project-id <id> --branch-id <id> list
seren endpoints --project-id <id> --branch-id <id> create \
  --name my-endpoint --compute-unit medium
seren endpoints --project-id <id> --branch-id <id> create \
  --name my-endpoint --autoscaling-min 1 --autoscaling-max 4
seren endpoints --project-id <id> --branch-id <id> update <endpoint-id> \
  --autoscaling-min 2 --autoscaling-max 8
seren endpoints --project-id <id> --branch-id <id> suspend <endpoint-id>
seren endpoints --project-id <id> --branch-id <id> start <endpoint-id>
seren endpoints --project-id <id> --branch-id <id> restart <endpoint-id>
seren endpoints --project-id <id> --branch-id <id> health <endpoint-id>
seren endpoints --project-id <id> --branch-id <id> metrics <endpoint-id>
seren endpoints --project-id <id> --branch-id <id> delete <endpoint-id>

Environment Files

seren env init --project-id <id>
seren env init --project-id <id> --branch-id <id> --key DATABASE_URL --pooled

Organizations

seren organizations                              # list organizations
seren orgs members --org-id <id>                  # list members
seren orgs invites --org-id <id>                  # list invites
seren orgs invite --org-id <id> --email [email protected] --role member

Agent Commerce

# Publishers
seren agent list-publishers
seren agent get-publisher <slug-or-id>
seren agent create-publisher --name "My API" --slug my-api \
  --organization-id <uuid> --wallet-address 0x... --wallet-network-id base-mainnet \
  --publisher-category integration --integration-type api --api-url https://...

# Prepaid balance (SerenBucks)
seren agent get-prepaid-balance
seren agent create-prepaid-deposit --amount 10.00
seren agent get-transaction-history

# Execute paid queries
seren agent execute-query --publisher <slug> --query "SELECT * FROM data LIMIT 10"
seren agent estimate-query-cost --publisher <slug> --query "SELECT * FROM data"

# x402 crypto deposits
seren agent get-deposit-requirements <publisher> <amount> <wallet-address>
seren agent get-supported

# Agent templates
# Supported template languages: python, typescript, javascript
seren agent list-templates
seren agent get-template <slug>
seren agent publish-template --name "My Agent" --slug my-agent \
  --code agent.py --language python --price "0.05"
seren agent invoke-template --slug my-agent --input '{"query": "..."}'

Managed Agents

Managed prompt-based agents run through the first-class seren-agent publisher. Use them when you want a hosted agent with prompt-defined behavior, publisher-backed tool presets, approval controls, revision history, and optional remote A2A delegation without shipping a code bundle.

See docs/managed-agents.md for the full guide.

# Deploy a read-oriented managed agent
seren agent deploy-prompt \
  --name "BTC Watcher" \
  --template research_monitor \
  --tool-preset live_data,database \
  --approval-policy read_only \
  --model-policy balanced \
  --model-id gpt-5 \
  --prompt "Track BTC/USD, use Seren publishers first, and return a concise summary."

# Inspect the resolved managed deployment
seren agent managed-get <deployment-id>
seren agent managed-revisions <deployment-id>

# Manage the deployment lifecycle through seren-agent
seren agent managed-start <deployment-id>
seren agent managed-stop <deployment-id>
seren agent managed-delete <deployment-id>

# Preview and apply remote A2A delegation settings
seren agent managed-preview <deployment-id> \
  --allow-remote-agent-origin https://agents.seren.ai \
  --allow-remote-agent-origin agents.internal

seren agent managed-update <deployment-id> \
  --allow-remote-agent-origin https://agents.seren.ai \
  --allow-remote-agent-origin agents.internal

# Preview, apply, or clear an eval gate
seren agent managed-preview <deployment-id> \
  --eval-gate-set-id <eval-set-id> \
  --eval-gate-max-age-seconds 86400

seren agent managed-update <deployment-id> \
  --eval-gate-set-id <eval-set-id> \
  --eval-gate-max-age-seconds 86400

seren agent managed-update <deployment-id> --clear-eval-gate

# Invoke the deployment
seren agent cloud run start --deployment-id <deployment-id> \
  --message "Give me the latest BTC update."

# See the org-wide activity overview
seren agent cloud overview
seren agent cloud overview --runs-limit 12 --approvals-limit 6

# Pull the same activity feed as JSON for automation
seren -o json agent cloud runs list --limit 20
seren -o json agent cloud approvals list --limit 20

Advanced managed-agent deploys can also use --agent-config <path> to supply raw tool_definitions. Each tool definition may include:

• timeout_override_seconds
• max_output_bytes

Cloud Activity

# Deployment inventory
seren agent cloud deployment list
seren -o json agent cloud deployment list

# Org-wide summary: deployments, recent runs, pending approvals
seren agent cloud overview

# Global activity feeds
seren agent cloud runs list --limit 20 --status running,awaiting_approval
seren agent cloud approvals list --limit 20

# Deployment-scoped activity feeds
seren agent cloud runs list --deployment-id <deployment-id> --limit 20
seren agent cloud approvals list --deployment-id <deployment-id>

# Resolve a blocked run inline
seren agent cloud run pending-approvals <run-id>
seren agent cloud run approve <run-id>
seren agent cloud run reject <run-id>

OAuth Connections (BYOC)

seren oauth providers                         # list available OAuth providers
seren oauth connections                       # list your connections
seren oauth connect <provider-slug>           # connect to a provider
seren oauth disconnect <provider-slug>        # disconnect

# Organization OAuth provider management
seren orgs oauth --org-id <id> list
seren orgs oauth --org-id <id> create --slug attio --name Attio \
  --authorization-url https://... --token-url https://... \
  --client-id <id> --client-secret <secret> --scope "read,write"
seren orgs oauth --org-id <id> update <provider-id> --name "New Name"
seren orgs oauth --org-id <id> delete <provider-id>

IP Allow List

seren ip-allow-list --project-id <id> list
seren ip-allow-list --project-id <id> add \
  --ip-address 192.168.1.0/24 --description "Office network"
seren ip-allow-list --project-id <id> remove <entry-id>
seren ip-allow-list --project-id <id> reset 10.0.0.0/8 172.16.0.0/12

VPC Endpoints

seren vpc endpoint --org-id <id> list
seren vpc endpoint --org-id <id> add \
  --region aws-us-east-1 --endpoint-id vpce-xxx --label production
seren vpc endpoint --org-id <id> get <endpoint-id>
seren vpc endpoint --org-id <id> remove <endpoint-id>
seren vpc project --project-id <id> list
seren vpc project --project-id <id> assign --vpc-endpoint-id <id>
seren vpc project --project-id <id> remove <assignment-id>

Branch Protection

seren branch-protection --project-id <id> list
seren branch-protection --project-id <id> get <branch-id>
seren branch-protection --project-id <id> create <branch-id> \
  --prevent-deletion --prevent-reset --require-approval
seren branch-protection --project-id <id> update <branch-id> \
  --require-approval true
seren branch-protection --project-id <id> delete <branch-id>

Logical Replication

seren replication --project-id <id> settings
seren replication --project-id <id> enable
seren replication --project-id <id> list-publications --branch-id <id>
seren replication --project-id <id> create-publication \
  --branch-id <id> --name my_pub --table users --table orders
seren replication --project-id <id> create-slot --branch-id <id> --name my_slot
seren replication --project-id <id> list-slots --branch-id <id>

Webhooks

seren webhooks --org-id <id> list
seren webhooks --org-id <id> create --name alerts \
  --url https://example.com/webhook \
  --event project.created --event branch.created
seren webhooks --org-id <id> get <webhook-id>
seren webhooks --org-id <id> update <webhook-id> --enabled false
seren webhooks --org-id <id> rotate-secret <webhook-id>
seren webhooks --org-id <id> deliveries <webhook-id>
seren webhooks --org-id <id> event-types
seren webhooks --org-id <id> delete <webhook-id>

Audit Logs

seren audit-logs --org-id <id> list --limit 100
seren audit-logs --org-id <id> get <log-id>

RBAC

seren rbac --org-id <id> list-roles
seren rbac --org-id <id> get-role <role-id>
seren rbac --org-id <id> create-role \
  --name developer --permission project.read --permission branch.create
seren rbac --org-id <id> update-role <role-id> --name "Senior Dev"
seren rbac --org-id <id> delete-role <role-id>
seren rbac --org-id <id> assign-role --member-id <id> --role-id <id>
seren rbac --org-id <id> list-permissions
seren rbac --org-id <id> my-permissions

Sessions

seren sessions list
seren sessions revoke <session-id>
seren sessions revoke-others <current-session-id>
seren sessions revoke-all

Billing

seren billing list-payment-methods
seren billing add-payment-method <stripe-pm-id>
seren billing remove-payment-method <id>
seren billing get-usage --organization-id <id> \
  --start-date 2025-01-01 --end-date 2025-01-31
seren billing generate-invoices --year 2025 --month 1
seren billing get-invoice <invoice-id>
seren billing issue-invoice <invoice-id>
seren billing health

Operations

seren operations --project-id <id> list
seren operations --project-id <id> get <operation-id>

Context Management

Set default project and organization to avoid passing --project-id repeatedly:

seren set-context set --project-id <id> --org-id <id>
seren set-context show
seren set-context clear

Output Formats

seren projects list                # table output (default)
seren projects list --format json  # JSON output
seren -o json projects list        # short form
seren -o json agent cloud overview # machine-readable activity summary

Environment Variables

Variable	Description
SEREN_API_KEY	API key for authentication
SEREN_API_BASE	Custom API base URL

Configuration

Config files are stored in:

• macOS/Linux: $XDG_CONFIG_HOME/seren/ with ~/.config/seren/ as the fallback
• Windows: %APPDATA%\seren\

Support

• Documentation: https://docs.serendb.com
• Issues: https://github.com/serenorg/seren/issues
• Discord: https://discord.gg/jseg7q4KS7

License

MIT License - see LICENSE for details.