Commands

Canvas CLI commands

The commands in this section allow you to manage project assets that involve Uniform's composition features. This includes:

Project assetCommandMore information
ComponentscomponentCapabilities
CompositionscompositionCapabilities
Data typesdatatypeCapabilities

note

The commands in this section require the package @uniformdev/canvas.

command
Fetch a component definition from the Uniform project.

CommandOutput details
-f, --format
string (optional, default value: YAML)
Format for the output. YAML JSON
-o, --filename
string (optional)
File name for the output. If not specified the output is written to stdout.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
List component definitions from the Uniform project.

CommandOutput details
--offset
integer (optional)
Number of rows to skip before fetching.
--limit
integer (optional, default value: 20)
Number of rows to fetch.
-f, --format
string (optional, default value: YAML)
Format for the output.
YAML JSON
-o, --filename
string (optional)
File name for the output. If not specified the output is written to stdout.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Fetch all component definitions from the Uniform project and save them locally.

  • If a directory path is specified, a separate file is created for each component.
  • If a file path is specified, all component definitions are saved in a single file.
CommandOutput details
-w, --what-if
boolean (optional)
If true, reports what would be done but changes no files.
-m, --mode
string (optional, default value: mirror)
Specifies what kind of changes can be made.
create - Create new files but don't update existing files.
createOrUpdate - Create new files and update existing files but delete no files.
mirror - Create new files, update existing files, and delete files that don't match components in the Uniform project.
-d, --diff
string (optional, default value: off)
Specifies which changes are written to stdout. If not specified, the environment variable UNIFORM_CLI_DIFF_MODE is used. If the environment variable isn't set, the default value is used.
off - No changes are written.
update - Only update changes are written.
on - Update, create, and delete changes are written.
-f, --format
string (optional, default value: YAML)
Format for the output. YAML JSON
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

tip

If file name is specified, CLI will override only corresponding part of it (for example, pulling Project Map will only override project map section, but leave Canvas section in the same file intact). It allows you to create single file containing whole project export (Canvas + Context + Project Map). This isn't recommended for big projects. Learn about backing up to a single file.

command
Insert or update all component definitions from local disk to the Uniform project.

  • If a directory path is specified, the components defined in the files in the directory used.
  • If a file path is specified, the components in the file are used.
CommandOutput details
-w, --what-if
boolean (optional)
If true, reports what would be done but changes no files.
-m, --mode
string (optional, default value: mirror)
Specifies what kind of changes can be made.
create - Create new files but don't update existing files.
createOrUpdate - Create new files and update existing files but delete no files.
mirror - Create new files, update existing files, and delete files that don't match components in the Uniform project.
-d, --diff
string (optional, default value: off)
Specifies which changes are written to stdout. If not specified, the environment variable UNIFORM_CLI_DIFF_MODE is used. If the environment variable isn't set, the default value is used.
off - No changes are written.
update - Only update changes are written.
on - Update, create, and delete changes are written.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Delete a component definition from the Uniform project.

CommandOutput details
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Insert or update a component definition from a local file to the Uniform project.

CommandOutput details
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Fetch a composition definition from the Uniform project.

CommandOutput details
-f, --format
string (optional, default value: YAML)
Format for the output. YAML JSON
-o, --filename
string (optional)
File name for the output. If not specified the output is written to stdout.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
List composition definitions from the Uniform project.

CommandOutput details
--offset
integer (optional)
Number of rows to skip before fetching.
--limit
integer (optional, default value: 20)
Number of rows to fetch.
-f, --format
string (optional, default value: YAML)
Format for the output.
YAML JSON
-o, --filename
string (optional)
File name for the output. If not specified the output is written to stdout.
--state
string (default value: preview)
Get the compositions that are in this state.
preview
published - Using this option without first pushing the draft compositions will result in "orphan" compositions and therefore isn't recommended.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Fetch all composition definitions from the Uniform project and save them locally.

  • If a directory path is specified, a separate file is created for each composition.
  • If a file path is specified, all composition definitions are saved in a single file.
CommandOutput details
-w, --what-if
boolean (optional)
If true, reports what would be done but changes no files.
-m, --mode
string (optional, default value: mirror)
Specifies what kind of changes can be made.
create - Create new files but don't update existing files.
createOrUpdate - Create new files and update existing files but delete no files.
mirror - Create new files, update existing files, and delete files that don't match components in the Uniform project.
-d, --diff
string (optional, default value: off)
Specifies which changes are written to stdout. If not specified, the environment variable UNIFORM_CLI_DIFF_MODE is used. If the environment variable isn't set, the default value is used.
off - No changes are written.
update - Only update changes are written.
on - Update, create, and delete changes are written.
-f, --format
string (optional, default value: YAML)
Format for the output. YAML JSON
--state
string (default value: preview)
Get the compositions that are in this state.
preview
published - Using this option without first pushing the draft compositions will result in "orphan" compositions and therefore isn't recommended.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

tip

If file name is specified, CLI will override only corresponding part of it (for example, pulling Project Map will only override project map section, but leave Canvas section in the same file intact). It allows you to create single file containing whole project export (Canvas + Context + Project Map). This isn't recommended for big projects. Learn about backing up to a single file.

command
Insert or update all composition definitions from local disk to the Uniform project.

  • If a directory path is specified, the compositions defined in the files in the directory used.
  • If a file path is specified, the components in the file are used.
CommandOutput details
-w, --what-if
boolean (optional)
If true, reports what would be done but changes no files.
-m, --mode
string (optional, default value: mirror)
Specifies what kind of changes can be made.
create - Create new files but don't update existing files.
createOrUpdate - Create new files and update existing files but delete no files.
mirror - Create new files, update existing files, and delete files that don't match components in the Uniform project.
-d, --diff
string (optional, default value: off)
Specifies which changes are written to stdout. If not specified, the environment variable UNIFORM_CLI_DIFF_MODE is used. If the environment variable isn't set, the default value is used.
off - No changes are written.
update - Only update changes are written.
on - Update, create, and delete changes are written.
--state
string (default value: preview)
Compositions are set to this state after being pushed.
preview
published - Using this option without first pushing the draft compositions will result in "orphan" compositions and therefore isn't recommended.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

info

it's important to understand the concept of composition state when using this command or else you might get unexpected results. See the --state switch for more information.

command
Publishes given composition.

  • If a compositionId is specified, then the specific composition will be published.
  • If "--all" param is specified instead - all compositions in the project will be published.
CommandOutput details
--all
boolean (optional)
If true, all compositions in the project will be published. Overrides "compositionId"
-w, --what-if
boolean (optional)
If true, reports what would be done but changes no files.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Delete a composition definition from the Uniform project.

CommandOutput details
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Insert or update a composition definition from a local file to the Uniform project.

CommandOutput details
--state
string (default value: preview)
Composition is set to this state after being updated.
preview
published - Using this option without first pushing the draft compositions will result in "orphan" compositions and therefore isn't recommended.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Fetch a data type definition from the Uniform project.

CommandOutput details
-f, --format
string (optional, default value: YAML)
Format for the output. YAML JSON
-o, --filename
string (optional)
File name for the output. If not specified the output is written to stdout.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
List data type definitions from the Uniform project.

CommandOutput details
--offset
integer (optional)
Number of rows to skip before fetching.
--limit
integer (optional, default value: 20)
Number of rows to fetch.
-f, --format
string (optional, default value: YAML)
Format for the output.
YAML JSON
-o, --filename
string (optional)
File name for the output. If not specified the output is written to stdout.
--state
string (default value: preview)
Get the compositions that are in this state.
preview
published - Using this option without first pushing the draft compositions will result in "orphan" compositions and therefore isn't recommended.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Fetch all data type definitions from the Uniform project and save them locally.

  • If a directory path is specified, a separate file is created for each composition.
  • If a file path is specified, all composition definitions are saved in a single file.
CommandOutput details
-w, --what-if
boolean (optional)
If true, reports what would be done but changes no files.
-m, --mode
string (optional, default value: mirror)
Specifies what kind of changes can be made.
create - Create new files but don't update existing files.
createOrUpdate - Create new files and update existing files but delete no files.
mirror - Create new files, update existing files, and delete files that don't match components in the Uniform project.
-d, --diff
string (optional, default value: off)
Specifies which changes are written to stdout. If not specified, the environment variable UNIFORM_CLI_DIFF_MODE is used. If the environment variable isn't set, the default value is used.
off - No changes are written.
update - Only update changes are written.
on - Update, create, and delete changes are written.
-f, --format
string (optional, default value: YAML)
Format for the output. YAML JSON
--state
string (default value: preview)
Get the compositions that are in this state.
preview
published - Using this option without first pushing the draft compositions will result in "orphan" compositions and therefore isn't recommended.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

tip

If file name is specified, CLI will override only corresponding part of it (for example, pulling Project Map will only override project map section, but leave Canvas section in the same file intact). It allows you to create single file containing whole project export (Canvas + Context + Project Map). This isn't recommended for big projects. Learn about backing up to a single file.

note

Data sources referred to in your data types must be created manually before a push can succeed. Data sources cannot be serialized because they contain secrets.

command
Insert or update all data type definitions from local disk to the Uniform project.

  • If a directory path is specified, the compositions defined in the files in the directory used.
  • If a file path is specified, the components in the file are used.
CommandOutput details
-w, --what-if
boolean (optional)
If true, reports what would be done but changes no files.
-m, --mode
string (optional, default value: mirror)
Specifies what kind of changes can be made.
create - Create new files but don't update existing files.
createOrUpdate - Create new files and update existing files but delete no files.
mirror - Create new files, update existing files, and delete files that don't match components in the Uniform project.
-d, --diff
string (optional, default value: off)
Specifies which changes are written to stdout. If not specified, the environment variable UNIFORM_CLI_DIFF_MODE is used. If the environment variable isn't set, the default value is used.
off - No changes are written.
update - Only update changes are written.
on - Update, create, and delete changes are written.
--state
string (default value: preview)
Compositions are set to this state after being pushed.
preview
published - Using this option without first pushing the draft compositions will result in "orphan" compositions and therefore isn't recommended.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

info

it's important to understand the concept of composition state when using this command or else you might get unexpected results. See the --state switch for more information.

command
Delete a data type definition from the Uniform project.

CommandOutput details
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.

command
Insert or update a data type definition from a local file to the Uniform project.

CommandOutput details
--state
string (default value: preview)
Data type is set to this state after being updated.
preview
published - Using this option without first pushing the draft compositions will result in "orphan" compositions and therefore isn't recommended.
-p, --project
string
Uniform project id. If not specified, the environment variable UNIFORM_CLI_PROJECT_ID is used.
--apiKey
string
Uniform API key. If not specified, the environment variable UNIFORM_API_KEY is used.
--apiHost
string (optional, default value: https://uniform.app)
Uniform host. If not specified, the environment variable UNIFORM_CLI_BASE_URL is used. If the environment variable isn't set, the default value is used.
--proxy
string (optional)
Proxy server. If not specified, the following environment variables are used (with the first match being used): HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy. If no match is found, no proxy server is used.