Pagesmith CLI Reference

The Pagesmith CLI lets you work with your sites from the terminal. Pull a project, edit files with any editor, and push changes back with a single command.

Installation

npm install -g @pagesmith-ai/cli

Requires Node.js 20 or later.

Authentication

Run pagesmith auth and paste your API key when prompted:

pagesmith auth
# Paste your API key: ps_live_...
# Authenticated. Config saved.

Get your API key from API Keys settings. The key is stored at ~/.pagesmith/config.json with restricted file permissions.

You can also pass the key directly. This is not recommended because it can appear in shell history:

pagesmith auth ps_live_your_key_here

Workflow

The typical workflow is pull, edit, push:

# 1. Pull a project to a local directory
pagesmith pull my-site

# 2. Edit files with any editor
cd my-site
# open in VS Code, Cursor, etc.

# 3. Check what changed
pagesmith status

# 4. Push changes: builds preview and auto-fixes errors
pagesmith push --message "update homepage"

When you push, Pagesmith:

1. Validates your code for issues
2. Commits the files to Git
3. Builds the preview
4. If the build fails, AI attempts to auto-fix (up to 2 retries)
5. If all fixes fail, the changes are rolled back

Commands

Projects

# List all your projects
pagesmith projects

Pull

# Pull project files to ./my-site/
pagesmith pull my-site

# Pull to a specific directory
pagesmith pull my-site --dir ~/projects/my-site

Status

# Show modified, added, and deleted files
pagesmith status

Run this inside a pulled project directory (where .pagesmith.json exists).

Push

# Push all changes
pagesmith push --message "update styles"

Costs 2 credits. If validation rejects the push (malicious code detected), no credits are charged.

Deploy

# Rebuild preview without changing files
pagesmith deploy

Useful after changing configuration or when the preview is stale.

Publish

# Publish to production
pagesmith publish

# Publish to a specific domain
pagesmith publish --domain example.com

AI Editing

# Send a natural language prompt to the AI editor
pagesmith prompt "Add a contact page with a form"

The AI modifies the files, commits, and builds the preview. Uses the same credit system as the web editor.

Content Management

# List content collections (e.g., blog)
pagesmith content

# List posts in a collection
pagesmith content blog

# Read a post
pagesmith content blog get my-post

# Create a post
pagesmith content blog create \
  --slug my-post \
  --title "My Post" \
  --body post.md \
  --field author=John \
  --field tags=news

# Update a post
pagesmith content blog update my-post \
  --title "Updated Title" \
  --field author=Jane

# Delete a post
pagesmith content blog delete my-post

The --field key=value flag lets you set arbitrary frontmatter fields. Repeat it for multiple fields.

Domains

# List custom domains
pagesmith domains

# Connect a domain (Pagesmith nameservers)
pagesmith domains connect example.com

# Connect with CNAME (manage DNS yourself)
pagesmith domains connect example.com --method cname

# Verify DNS ownership
pagesmith domains verify <domain-id>

# Set primary domain
pagesmith domains set-primary <domain-id>

# Refresh SSL certificate
pagesmith domains refresh-ssl <domain-id>

# Remove a domain
pagesmith domains remove <domain-id>

Secrets

# List integration secrets
pagesmith secrets

# Set secrets for an integration
pagesmith secrets set mailchimp preview API_KEY=mc_abc123

History

# Show recent commits
pagesmith history

# Show more
pagesmith history --limit 50

Environment Variables

Project Context

Most commands auto-detect the project by looking for a .pagesmith.json file in the current directory or parent directories. You can also pass a project name or UUID explicitly:

pagesmith deploy my-site
pagesmith history my-site --limit 10