• Documentation
  • Pricing
© 2026 Serverless, Inc. All rights reserved.

Framework

  • Overview
  • Documentation
  • Plugins360
  • Pricing

Learn

  • Blog
  • GuidesUpdated
  • Examples240
  • Courses

Resources

  • Support
  • Security
  • Trust Center
  • Status

Community

  • Slack
  • GitHub47k
  • Forum
  • Meetups

Company

  • About
  • Careers
  • Contact
  • Partners

Legal

  • Terms of Service
  • Privacy Policy
  • Trademark
  • DMCA
Serverless Framework Logo

Serverless Framework

Intro
SetupUpgrading To V4ConceptsTutorialAWS CredentialsLicense Keys
DeployingPackagingBuildingTestingDev ModeServicesFunctions
OverviewHTTP (API Gateway v2)REST (API Gateway v1)ActiveMQApplication Load BalancerAlexa SkillAlexa Smart HomeCloudWatch EventCloudWatch LogCloudFrontCognito User PoolEventBridge EventIoTIoT Fleet ProvisioningKafkaKinesis & DynamoDBMSKRabbitMQS3ScheduleSNSSQSWebsocket
LayersManaged InstancesWeb Apps (Lambda Web Functions)Sandboxes (Lambda MicroVMs)MCP ServersAlertsVersion PruningDomainsIAM Function PermissionsParameters
OverviewSelf-reference serverless.ymlServerless CoreEnvironment VariablesCLI OptionsExternal YAML/JSON FilesJavascript propertiesGitDoppler
OverviewS3 ObjectsSSM Parameter Store & Secrets ManagerCloudFormation Stack Outputs
OverviewVaultTerraform State Output
ResourcesComposing ServicesDeployment BucketStateAgent SkillsPython support
OverviewRuntimeGatewayMemoryBrowserCode InterpreterDev Mode
API Gateway Proxy
OverviewGeneral ConfigurationAuthenticationAPI KeysData SourcesResolversPipeline FunctionsSubstitutionsCachingDelta SyncCustom DomainWAFCLI Commands
Deploying SAM/CFN TemplatesWorkflow Tips
OverviewCreating PluginsCLI OutputCustom CommandsCustom VariablesExtending the Configuration schemaExtending and overriding configuration
OverviewDashboardAxiom
Overviewagent docsagent inspectagent setupagent skills installagent skills list / readdeploydeploy functiondeploy listdevdiffinfoinvokeinvoke localloginlogin awslogin aws ssologsmetricspackageplugin installplugin uninstallprintprunereconcileremoverollbackrollback functionusage
OverviewConcepts
OverviewMetricsTracesTroubleshoot
OverviewNode.jsPython
OutputsProviders
OverviewBranch DeploymentsPreview DeploymentsCustom ScriptsTestingPrivate PackagesNotificationsMono ReposDeploy in your own CI/CDBest PracticesTroubleshootingFAQ
OverviewSetupToolsAWS Integration
Serverless.yml Reference
Examples and TutorialsConfiguration Validation
  1. Usage
  2. App Sync
  3. CLI Commands

AppSync CLI commands

The serverless appsync commands work with the AppSync API of the service in the current directory: they validate its schema, export its introspection schema, flush its cache, open its consoles, print its logs and manage its custom domain. They are available when serverless.yml has an appSync block.

To check the schema before deploying:

serverless appsync validate-schema

get-introspection, flush-cache, console, cloudwatch, logs, domain assoc and domain disassoc read the API ID from the service's deployed CloudFormation stack, so deploy the service first; they stop with AppSync Api not found in stack. Did you forget to deploy? when the stack has no API. All commands take the usual --stage, --region and --aws-profile options to select the stack and the AWS credentials.

Validate the schema

serverless appsync validate-schema checks the appSync configuration and the GraphQL schema files locally, with the AppSync directives and scalars predefined, and makes no AWS calls:

serverless appsync validate-schema

A valid schema prints AppSync schema valid. An invalid one stops the command with Invalid GraphQL schema: followed by each error.

Problems in the appSync configuration follow configValidationMode: with the default warn, the command prints Invalid AppSync Configuration as a warning and still prints AppSync schema valid when the schema is valid. To make validate-schema stop on configuration problems, for example in CI, set configValidationMode: error at the top level of serverless.yml.

Export the introspection schema

serverless appsync get-introspection downloads the deployed API's schema from AppSync and prints it, or writes it to a file:

serverless appsync get-introspection --format SDL --output schema.deployed.graphql
OptionShortcutValueDefaultDescription
--format-fJSON or SDL (any case)JSONThe output format: an introspection result in JSON, or GraphQL schema language.
--output-ofile pathstdoutThe file to write, relative to the current working directory. An existing file is overwritten.

Flush the cache

serverless appsync flush-cache deletes every entry in the API's server-side cache, so the next requests read from the data sources:

serverless appsync flush-cache --stage prod

It prints Cache flushed successfully. The API must have a cache (appSync.caching).

Open the AppSync console

serverless appsync console opens the API's page in the AWS AppSync console, in the default browser:

serverless appsync console

Open the CloudWatch logs console

serverless appsync cloudwatch opens the API's log group (/aws/appsync/apis/<api id>) in the CloudWatch console, in the default browser:

serverless appsync cloudwatch

The console and cloudwatch commands print nothing; on a machine without a browser, such as CI, they have no effect.

Print the API logs

serverless appsync logs prints events from the API's log group, /aws/appsync/apis/<api id>, one per line as <ISO timestamp><tab><message>. The API needs logging turned on:

serverless appsync logs --startTime 1h --filter ERROR
OptionShortcutValueDefaultDescription
--startTimeNoneISO 8601 date-time, or a duration such as 30m, 2h, 1d10mThe earliest event to print. A duration counts back from now; a number without a unit is hours.
--filter-fCloudWatch Logs filter patternNonePrints only matching events, such as a request ID.
--tail-tNoneOffKeeps polling for new events until you stop the command.
--interval-imilliseconds1000With --tail, the time between polls.

Without --tail, the command prints one page of results (up to 10,000 events or 1 MB) and exits.

Manage the custom domain

The serverless appsync domain commands create, associate and remove the custom domain of the API outside CloudFormation. Use them with domain.useCloudFormation: false in serverless.yml; they read the domain settings (name, certificateArn, hostedZoneId, hostedZoneName) from the appSync.domain block.

To set up a domain and point it at this stage's API, run:

serverless appsync domain create --stage prod
serverless appsync domain assoc --stage prod
serverless appsync domain create-record --stage prod

When domain.useCloudFormation isn't false, each domain command first warns that it can cause drift from the CloudFormation stack and asks Do you want to continue? y/N. Some commands ask again before a destructive step. The questions read from the terminal, so in CI and other runs without a terminal pass --yes (-y), which answers yes to every question. Answering no at the drift question exits with code 0 and changes nothing.

CommandWhat it does in AWSOptions
domain createCreates the AppSync domain name with certificateArn, or with an issued us-east-1 ACM certificate for name or its wildcard.--quiet, --yes
domain assocAssociates the domain with this stage's API and waits until the association succeeds. Asks before replacing an association with another API.--yes
domain create-recordCreates a Route 53 A alias record for name pointing at the domain, and waits until it is in sync.--quiet, --yes
domain delete-recordDeletes that Route 53 record, after a confirmation.--quiet, --yes
domain disassocRemoves the domain's association with this stage's API, after a confirmation, and waits until it is gone.--force, --yes
domain deleteDeletes the AppSync domain name, after a confirmation. Disassociate the API first.--quiet, --yes

The domain options:

OptionShortcutDescription
--yes-yAnswers yes to every confirmation question.
--quiet-qLogs an error instead of failing the command, for example when the domain already exists or No certificate found for domain api.example.com.
--force-fWith disassoc: removes the association even when the domain points at an API from another stage or stack.

create-record and delete-record find the hosted zone by hostedZoneId, else by hostedZoneName, else by the parent domain of name. create-record needs the domain to exist, and otherwise stops with Domain api.example.com not found.

Warning: domain delete and domain disassoc take the custom domain offline for every client that uses it.

Related pages

  • AppSync custom domain
  • AppSync caching
  • AppSync API configuration
  • AppSync overview
Edit this page
Prev WAFNextDeploying SAM/CFN Templates

Contents

  • AppSync CLI commands
  • Validate the schema
  • Export the introspection schema
  • Flush the cache
  • Open the AppSync console
  • Open the CloudWatch logs console
  • Print the API logs
  • Manage the custom domain
  • Related pages

Related

GuidesPluginsExamplesSlack CommunitySupport