Swanky CLI is a Node.js based CLI application that abstracts away and extends the functionality of Polkadot.js,
cargo contract, and other ink! based smart contract developer tools.
It aims to ease development of and interaction with ink! smart contracts and provides simple tools to bootstrap contract environment (project) with contract and integration tests templates, local node and accounts management, smart contracts interaction on both local and remote networks, compatibility checks between the contract pallet and compiler...
It also comes with a preconfigured Docker image and .codespaces configuration for easy dev environment setup.
With all of the features mentioned above, even more is in active or planned development. The whole project is public, and everyone is welcome to contribute or suggest features:
Templates provided in the current version of swanky-cli, as well as environment in the swanky-base image, and supported tools target ink! v4, and use
cargo contract v2.
Cargo contract v3 introduced breaking changes to how artifacts are stored and you'll have to move them manually if you wish to use it.
The CLI can be installed and used in different ways:
- using a preconfigured environment of a dev-container locally with VS Code
- using the dev-container in a cloud-based environment such as GitHub Codespaces or Gitpod
- using the swanky-base container image locally (same is used in the dev-container)
- downloading a precompiled binary
- as an npm package (installed globally, or via the
Note that using the precompiled binaries, NPM, or compiling it yourself requires you to have the local environment set up correctly
Using dev container is the easiest way to use
swanky-cli, it includes all the environment setup and will support auto-updates in the future.
To run your project in the dev container follow the steps on swanky-dev-container Github.
Cloud based environments
Similar to using the dev container locally, GitHub will detect the
.devcontainer config in your project and let you run the project in a cloud-based IDE.
You'll have to sign up for an account to use Gitpod, but the process is the same.
Currently it is not possible to forward ws:// ports from GitHub Codespaces, so if you'd like to interact with the swanky-node from contracts-ui or a similar service, use Gitpod or one of the other methods.
Download the precompiled binaries
Download the correct archive for your platform from the releases section of swanky-cli github page.
Extract the archive to the appropriate location, for example the
swankyexecutable to your path variable by creating a symbolic link to it from a common
bindirectory or somewhere similar.
ln -s /Users/my_name/software/swanky-cli/bin/swanky /usr/local/bin
ln -s /home/my_name/swanky-cli/bin/swanky /usr/local/bin
Globally with npm
This approach may seem simpler, but due to the nature of
Node.js dependency management, may result in version inconsistency or other errors.
$ npm install -g @astar-network/swanky-cli
$ npx @astar-network/swanky-cli [command]
If you're using a dev container, or have followed the installation instructions, you should have
swanky command available in your terminal.
Running it without any arguments (or with
--help) will provide you with a list of top-level commands and the app version.
help as an argument and providing it
--nested-commands flag will show full list of commands, including nested ones:
swanky help --nested-commands
Note that every command and subcommand also supports
--help flags to display their usage instructions.
Likewise, most of the commands support
--verbose flag, which you can use to get more detailed output (useful for debugging and reporting errors).
Bootstrap a new project
swanky init command, you'll be prompted for a series of answers to define your project and the first smart contract within it.
After gathering all the required information, the app will proceed to check your environment, scaffold the project, download and install (optionally) swanky node and the project dependencies.
swanky init PROJECT_NAME
The resulting folder structure should look something like this:
If you want to start from a more complete example like those in the swanky-dapps repo, or rmrk-ink, or you want to convert your existing contract to a swanky project, you can use
swanky init --convert command.
It will prompt you for locations of your contract files, as well as additional crates and tests.
In the last step, you'll be provided a list of files to be copied over and you'll be able to deselect any of them that are maybe not needed.
Swanky will look for a common ink! configuration, and will do it's best to copy everything to equivalent paths, but it is likely that you'll have to adjust some configs and import paths manually after conversion.
Check dependencies and compatibility
You can quickly check the presence and versions of required dependencies by running
swanky check command.
For now, you will need to be be in a project folder to run this command.
This command will be updated to fix that, and provide more useful information.
Create and list accounts used for contract interaction.
These are the accounts stored inside your
swanky.config.json, so the command needs to be ran from within the project directory.
During account creation you'll have an option of passing your own mnemonic, or have Swanky generate one for you by passing
You can also mark the account as "production" which will require you to set a password and encrypt the mnemonic.
Be careful not to use a dev account on live networks, as their mnemonic is stored in plain text in the config!
Newly generated accounts that are not the preconfigured dev accounts (Alice, Bob, Charlie...) will have no funds initially, so you'll have to transfer some manually.
Interact with contracts
swanky contract command offers several subcommands for different interactions with your contracts.
The command names are self explanatory, and to get more detailed information on using a specific command, you can use the help flag with it:
swanky contract SUB_COMMAND --help
Your contracts are listed in
swanky.config.json, and can be referred to by
name field. Calling
swanky contract compile CONTRACT_NAME will run cargo-contract compiler, generate TS types using Typechain, and move the artifacts and types to appropriate locations for later usage.
If you have multiple contracts and wish to compile them all at once, you can pass the
--all flag instead of the contract name.
Likewise, if you're compiling for production, you need to pass the
Get detailed contract description
Compiling the contract will generate it's metadata too.
contract explain CONTRACT_NAME command to get a more human friendly version of that metadata:
Run E2E tests
Please note these tests are not ink! E2E tests, but are written in TypeScript, and require a local node to be running.
You can get more information on ink! E2E test framework in the ink! documentation.
A contract template will provide you with a simple test as well, which you can use as a starting point.
The tests utilize @polkadot/api library, and contract types generated by typechain-polkadot.
The types are generated during the compile step and copied to
typedContract/contract_nae directory, and in the
tests/*/artifacts/ directory. If you need only the types generated
(if you for example deleted or edited them), you can do that without going through the whole compilation step by using
swanky contract typegen command.
swanky contract test CONTRACT_NAME will detect all
*.test.ts files in the
tests/contract_name/ directory, and run them sequentially, or in all directories inside
tests/ if you pass the
Running the tests programmatically may throw warnings about duplicate dependencies on
This occurs because those libraries are included in swanky app itself, as well as in the test files.
Apart from the warning text spamming, no negative consequence of this has been observed.
If you want to avoid the warnings anyway, you can run tests as a yarn/npm command:
yarn test or
npm run test
Web based report will be generated and stored in
tests/*/testReports directory. You can copy the path of the reports and use the
serve app to view them in browser. (
serve is included in swanky-dev-container)
Deploy your contract
When your contract is compiled and tested, you can deploy it to a local node or a remote network.
You will need to supply account you wish to deploy the contract from (
--account), and any arguments required by your contract's constructor (
By default, your contract will be deployed to a local node, but you can pass a custom network via
--network flag. Available networks are configured in
Successfully running the
deploy command will print out the address your contract is deployed to, as well as save it into
Run queries and transactions
Once your contract is deployed, you can call it from the CLI using
query for read-only calls, and
tx for the calls that change the chain state and require signing (and a gas fee).
Both commands require
MESSAGE_NAME parameters, and for
tx a caller account needs to be provided too. (
If the message you're calling requires arguments to be passed, you can do that using
Result of a
query is straight forward,
OK followed by what ever the response is.
The transaction (
tx) is a bit more raw though. Important to note are the
internalError fields, plus the
If the errors are
undefined, and the status
finalized, your transaction has been successful.
Gas fee for
tx is calculated and applied automatically, but you can provide a gas limit manually by using the
Keep in mind that the transaction will fail if you provide too low a value.
Add a new contract from template
You can create additional contracts in the same project, using the
contract new command and selecting from predefined templates.
The contract will be referred by
name when using the relevant contract commands, and you can check the details in
Interact with a local node
If you have chosen to download and use the Swanky Node during init step, you can use
swanky node commands to start and manage it.
swanky node start will start the node, and the node will preserve the state across restarts.
If you want to reset the node state, use the
swanky node purge command.
Note that node needs to be running if you are using a default local network with
If you chose not to download the swanky-node during the
init, or you changed the OS environment (for example switched to inside a dev container after running
init on host OS, or vice-versa), you can run
swanky node install
to download the node for currently running platform.
If you want to use an external UI to interact with the node, you might run into some CORS issues.
This can be solved by passing a custom array of whitelisted urls using the
Swanky CLI's functionality can be extended by the use of plugins, and it's a way to add new, case specific commands without modifying the core codebase.
One WIP example is the Phala plugin