The Fission Command Line Interface (CLI)
The Fission CLI is a developer tool for working with apps and managing your account on the Fission platform.
The Fission CLI uses multipart commands with the structure:
Commands group related subcommands into operations on apps or accounts. Options extend functionality or display help information.
Shortcuts combine a command and subcommand into a shortcut command:
The options that would apply to the multipart command also apply to the shortcut.
This guide covers the most commonly used options. More options are available for you to explore and you can always join our Discord to ask us more about them!
The --help option displays a quick reference at any command level.
At the top level, fission --help displays a high-level summary of all commands and shortcuts.
The Fission CLI commands to work with apps
Use the fission app command and its subcommands to work with apps. The main operations are registering an app, publishing an app, and displaying information about an app.
The fission app register command initializes a new app and links it to your Fission account.
You will be prompted for a build directory. The Fission CLI will publish your app from the build directory you select.
If you are using a common build directory, the Fission CLI will detect it when you run fission app register and suggest it. You accept the suggestion or enter another build directory as a relative path from the fission.yaml file.
The Fission CLI will create a fission.yaml configuration file with a list of files to ignore, a URL where your app will be viewable after it is published, and a build directory. See the Fission YAML guide for more information about the fission.yaml file.
You can also use a custom domain name for your app. See the Custom Domains guide to set up a custom domain name.
The fission app register command has advanced options:
Use the fission app publish command to publish your app to the web. Run this command from the directory that contains your app's fission.yaml configuration file.
The fission app publish command publishes your app and associates it with the URL in the fission.yaml file. After your app is published, the Fission CLI will output a success message and the URL for your app.
The fission up command is a shortcut for fission app publish.
The fission app publish command has advanced options:
You can continuously publish your app by adding the --watch option. The Fission CLI will watch your build directory and publish whenever it detects a change.
This means that as you work in your local development environment, changes are continuously streamed online as you save. Note that some development environments have different code and output options than "production", but this will allow you to quickly and easily share a live online version with other people.
Use fission app info to display the URL where your app is viewable.
The fission app delegate command delegates the capability to work with apps to a DID:
You can delegate apps you have registered on your machine or delegate from environment variables by setting FISSION_MACHINE_KEY and FISSION_APP_UCAN to an Ed25519 private key and a UCAN whose audience is associated with the key. Both environment variables must be set.
The command assumes least privilege by defaulting to Append potency and limiting the UCAN lifetime to five minutes. Both potency and lifetime can be set when more potency or a longer lifetime are desired.
The fission app delegate command has advanced options:
More information on global and app YAML configuration files.
Fission stores global and app configuration options in YAML files. The global configuration is stored in a config.yaml file and app configurations are stored in fission.yaml files.
After you run fission user setup, you will have a global config.yaml in your ~/.config/fission/ folder. You can open config.yaml in a text editor or display it at the command line.
The default global config.yaml will looks something like this:
In most cases, the only thing you will want to change in this file is the ignore section. The other sections are managed by the Fission CLI.
Ignore is a list of files you don't want fission app publish to publish. For example, you might add commonly ignored files and secrets.
Ignore follows the same conventions used in a .gitignore file.
Username is a name you select for yourself during fission setup.
The UCAN that was used to link from another device or browser. null if the account was created on this device.
Server DID is the identity of the Fission server that authenticates your requests when using the Fission CLI.
We configure your machine to directly connect to our servers. The peers are the IP addresses and fingerprints of our servers.
You can also fetch our active public peers from the peers endpoint: https://runfission.com/ipfs/peers
Eventually, we'll have a list of peers around the world.
Timestamp of the last check for an updated version of the CLI.
The path to the key used to sign requests made when using the Fission CLI.
When you create a new app with fission app register, a fission.yaml file is created in the directory where you ran the command. The default fission.yaml file looks something like:
Ignore works the same as the ignore in the global configuration. You can use it to list files that you do not want to publish.
You might use it to ignore a directory like node_modules or all files with an extension like Photoshop .psd files.
YAML can specify lists in a couple of different ways, both like this, or as comma-separated list shown in the global config.yaml example above.
The URL where your app is viewable after it has been published.
Eventually, you will be able to publish different versions of your app -- for example, development, testing, production, etc. -- and use custom domains for your app.
The build directory is the directory the Fission CLI will publish. Use this when you have a build step that produces a production-ready version of your application.
The build directory is set as a relative path from the location of the fission.yaml file.
If you are using a well-known build directory, the Fission CLI will attempt to detect it the first time you run fission app register. It will prompt you and ask if you would like to use the directory it detects.
The Fission CLI commands for generating credentials
Use fission generate credentials to generate key pairs and DIDs.
The fission generate credentials command generates a new Ed25519 key pair and an associated DID.
See the W3C did:key Method specification for details on the derivation of DIDs from public keys.
Generated key pairs are not stored anywhere and are not associated with your Fission user account. Be careful to store a copy somewhere safe.
The Fission CLI account management commands
Use fission setup, fission user whoami, and fission login to set up your account, display your username, and link your account in web browser.
The fission setup command registers your account with Fission or links to your existing Fission account.
When you register a new account, you will be prompted for a username and an email. Fission will send you an email to confirm your account and complete your registration.
The fission setup command will create a global config.yaml file in your ~/.config/fission directory. See the Global Fission YAML guide for more information about the config.yaml file.
The registration process will also create a Fission Drive for you automatically at the URL YOURNAME.fission.name using your Fission username.
Use fission user whoami to display your username.
You can link your Fission account in a web browser to interact with Fission-enabled apps. The fission login command sets up the CLI to listen for requests to link your account.
Open the Fission auth lobby in a browser window, select "Sign In", enter your Fission username, and select "Link Account".
The browser window and command line will display confirmation codes. Verify that the confirmation codes match and grant access at the command line.
The browser window will update to show that you have successfully linked your account.
If you are signed into a Fission account in a web browser, you can link your account and use it at the command line.
Open the Fission auth lobby in a browser window.
Use fission setup to create and link a CLI user at your command line.
When prompted, enter Y to confirm you have an account and enter your username from the browser window. The auth lobby and CLI will display a confirmation code.
When you have confirmed that the codes match, approve in the browser, and the CLI will complete the setup process and link your account.
You can set up your machine with an existing account if you have the machine_id.ed25519 key. Use --with-key argument and the path to your key.
