Use Futurecast from the command line

The Futurecast CLI lets you work with Futurecast by typing commands on your computer.

The Futurecast CLI lets you work with Futurecast by typing commands on your computer. CLI means command-line interface. You type in an app such as Terminal, then read the result.

This option gives you more control over repeated tasks. You can turn a file of goals into futures, organize several boards, or connect Futurecast to a script. A script is a saved set of commands that a computer can run for you.

Futurecast CLI is its own tool. Claude Code is a separate AI assistant that can use terminal tools. If an assistant can run commands on your computer, it can help you use Futurecast CLI after you approve access.

For a conversation in ChatGPT or Claude, start with Connect an AI assistant.

Before you begin

You need:

• Futurecast on your iPhone, with the library you want to use.
• An internet connection on your phone and computer.
• A computer with Node.js and npm. Node.js runs the CLI. npm installs it.

If you need Node.js, choose the LTS version on the official Node.js download page. LTS means long-term support. Futurecast requires Node.js 20 or later. Choose a currently supported LTS release when installing it.

Open Terminal on a Mac, or your usual terminal on Windows or Linux. Run each line separately:

node --version
npm --version

Each command should show a version number. If either command is missing, follow the Node.js and npm installation guide.

1. Install Futurecast CLI

Run:

npm install -g futurecast

The -g option makes the futurecast command available from any folder. This is the install command on the Futurecast developer page.

Check the installation:

futurecast --version
futurecast --help

The first command shows the installed version. The second lists the commands you can use.

2. Connect it to your app

To read your library and create or organize content, run:

futurecast login --scopes read,write

Here, scopes means permissions. This command requests Read and Write. Write also allows changes and deletions. It does not request permission to generate images.

If you only want to view your library, use futurecast login --scopes read instead.

1. Leave the terminal open. Your computer's browser opens a Futurecast pairing page.
2. On your iPhone, open Futurecast.
3. Tap Today and open your profile.
4. Tap Connected Agents, then Pair an Agent.
5. Enter the code from your computer's browser. Tap Continue.
6. Check that the connection is named Futurecast CLI.
7. Review its permissions. Tap Approve to connect, or Decline to stop.
8. Return to the browser on your computer. Leave that page open while it finishes.
9. Return to the terminal. Wait for Connected before using other commands.

You can also scan the browser page's QR code with your iPhone camera. This opens the pairing request in Futurecast.

If the browser does not open, the CLI prints a link. Open that link in a browser on the same computer where the command is running. The phone approves access, but the browser must finish connecting to that computer.

The code expires after five minutes. If the code or login expires, run the login command again and use the new code.

3. Check the connection

Run:

futurecast status
futurecast boards

status shows the connection, permissions, library sync, and the number of changes waiting for your phone. boards lists the boards available to this connection.

The CLI reads a synced copy of your library. Open Futurecast on your phone and leave it online if the catalog is empty or still syncing. Catalog means the library copy available to connected tools. An empty result does not always mean that your phone has no boards.

Boards with Hide from Agents turned on are left out. Their futures are hidden from connected tools too.

To find a board by name:

futurecast boards --matching "Calm"

Each result has an ID. This is the unique value that identifies an item. Commands use IDs so that two boards with the same name do not get mixed up.

To see the futures on a board, replace BOARD_ID with its ID:

futurecast futures --board BOARD_ID

4. Create a board and a future

This example creates real content in your library. Use it when you want a board called Steady Days.

1. Run this command:

   futurecast create-board "Steady Days" --intention "Stay focused and make time for what matters." --wait

2. Open Futurecast on your phone and keep it online. Wait for the terminal to show Applied.

3. Find the new board with futurecast boards --matching "Steady Days". Copy its ID.

4. Replace BOARD_ID below with that ID. Run the command:

   futurecast create-future "I give my attention to what matters." --board BOARD_ID --wait

5. Wait for Applied, then open the board on your phone.

6. Review the words. When you are ready, play the board or add it to your Daily Ritual.

The board's intention is a short note about what the board is for. A future is a statement you want to practice. These commands create text content. They do not generate an image.

Understand "Queued" and "Applied"

Queued means Futurecast received the request. Your phone still needs to apply it. Open Futurecast on your phone to let it do that.

Applied means the phone completed that command. Failed means it could not complete it. Read the reason before making another request.

The --wait option keeps the command open while it checks for a result. Ctrl-C stops that check. It does not cancel the request, which can still finish on your phone.

To check later, replace COMMAND_ID with the command ID shown in the result:

futurecast commands COMMAND_ID

The CLI stops waiting after about ten minutes. A queued request can remain available for up to 72 hours. An expired result means it did not apply in time. Do not repeat a creation command because the wait ended. Check its status first so that you do not create a second copy.

More control

Use futurecast --help to see the exact options for these tasks:

Some options use affirmation as a technical label, such as --affirmation. This means the words of a future. Keep the option name as shown in the command help.

Removing a future from a board leaves the future in your library. Deleting it moves it to Recently Deleted, where you can restore it for 30 days. The delete-board option --include-futures also moves the board's futures there. This affects any other boards using those futures. Review the affected items before using delete commands.

Image generation needs both Write and Visions permission and spends your image allowance. If you want this access, reconnect with futurecast login --scopes read,write,visions and approve it in the app. Running futurecast login without a scopes option requests all three permissions.

Use it in a script or with an AI assistant

Add --json for output that a script can read. JSON is a structured text format. For example, this command reads your boards:

futurecast boards --json

For writes, give each intended change a unique --idempotency-key. This is a name your script saves for that one request. Reuse the same key only when retrying that same request. Use a new key for a different change. This helps avoid duplicate content after a lost connection.

Save the returned command_id. Check it before reporting success or retrying. A command that exits without an error can still be queued. With --json --wait, the CLI can print more than one JSON object on separate lines: the initial response, then the final result.

An assistant with terminal access can check prerequisites, help install the CLI, and start login. You still approve access on your iPhone. It should check a read command before making changes. Give it your intended task, such as turning an approved list of goals into a board. Do not paste login credentials into chat.

For the full command data format, use the Futurecast API reference. An API is a way for software tools to exchange requests and results.

Disconnect the CLI

On your computer, run:

futurecast logout

This removes the saved login for this computer's CLI. It does not revoke the connection itself.

To revoke its access, open Futurecast > Profile > Connected Agents > Futurecast CLI. Tap Disconnect Agent, then Disconnect. Do this if you no longer trust the computer or a copy of its credentials.

The CLI saves login credentials in ~/.futurecast/credentials.json under your computer account. ~ means your home folder. This is a local file, not a password vault. Do not upload it, paste it into a chat, or include it in a shared project.

If something is not working

If you need help, contact support. Share the command name, error message, and CLI version. Leave out credentials and personal future text.

Back to connected assistants · Back to Futurecast Help